diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md new file mode 100644 index 0000000..2929c78 --- /dev/null +++ b/GETTING_STARTED.md @@ -0,0 +1,152 @@ +# Running your own OSE server + +Install **Python 3.10 or newer**, then extract the entire release into a folder you can write to. OSE does not require Docker or a separate database service. + +## First run + +On **Windows**, double-click `Start-OSE.cmd`. You can also open PowerShell in the OSE folder and run: + +```powershell +powershell -ExecutionPolicy Bypass -File .\Start-OSE.ps1 +``` + +On **Linux or macOS**, open a terminal in the OSE folder and run: + +```sh +sh start-ose.sh +``` + +The script creates a `.venv` inside the OSE folder and installs the packages from `requirements.txt`. It does not install operating-system packages or change your system Python packages. If Python reports that venv support is missing, install that component through your operating system and retry. + +Setup asks for: + +1. Your server's name. +2. Its listen port, normally `8080`. +3. Its listen address, normally `0.0.0.0` for local-network access. +4. Your administrator username and password. + +Choosing another administrator disables the bundled `reximemo` / `alpine` login. Existing accounts and sample Flipnotes are kept. Passwords are not saved in the JSON settings file. + +Open **http://127.0.0.1:8080/** on the server computer, adjusting the port if you changed it. Keep the terminal open; **Ctrl+C** stops OSE. Later launches reuse the environment and settings. Dependencies are reinstalled only when `requirements.txt` changes. + +To repeat setup, run `python manage.py setup` using the environment's Python executable. + +## Manual installation + +On Linux/macOS: + +```sh +python3 -m venv .venv +.venv/bin/python -m pip install -r requirements.txt +.venv/bin/python manage.py setup +.venv/bin/python server.py +``` + +On Windows, use `.venv\Scripts\python.exe` instead of `.venv/bin/python`. The start scripts do these steps for you. + +To expose the optional technical manual at `/docs`, pass `docs:enabled`: + +```sh +sh start-ose.sh docs:enabled +``` + +On Windows, use `Start-OSE.cmd docs:enabled` from a terminal. Directly running `server.py docs:enabled` also works. + +## Connect a DSi + +OSE provides the historical Hatena HTTP server/proxy. Nintendo NAS, DNS and authentication services are supplied separately. + +1. Configure the DSi to use the **official RexiMemo DNS service**, or another functional DNS/auth/NAS service. +2. Enable **Proxy Server** in that DSi connection. +3. Enter the server computer's local-network IP address. +4. Set the proxy port to `8080`, or your configured port. +5. Keep OSE running and open Flipnote Studio's online service. + +The OSE terminal prints available **DSi HTTP proxy** addresses. Do not enter `127.0.0.1` on the DSi: that would refer to the DSi itself. Both devices must be able to reach each other. Your firewall may need to allow the configured port on your local network. + +With listen address `127.0.0.1`, only the server computer can connect. Use `0.0.0.0` for a DSi on the network. OSE retains the existing regional DSi resource paths, `X-DSi-SID` gate and original PPM download responses. + +## Manage the site + +Sign in, then open **Admin**. From there you can manage channels, server branding, posting options, content hiding and IP bans. Search and channel browsing are available on the web and DSi. + +**Manage Flipnote** appears for a Flipnote's owner and administrators. It controls its title, description, channel and removal. Hiding a Flipnote or comment is separate from removing it: an administrator can restore hidden content. Hidden content is not sent through normal DSi lists or file routes. + +An original PPM remains unchanged by editing its website details or rendering a thumbnail. Web playback and explicit downloads also retain their separate counters. + +OSE keeps its reference **IP-to-account login model**. People sharing a public IP can share login state, and guest ownership is also tied to the IP address. Password storage remains the reference edition's simple SHA-256 digest. The setup helper replaces the public default administrator credential; it does not reproduce production RexiMemo authentication or verify console ownership. + +## Settings + +`server-settings.json` contains readable server settings and is excluded from Git by default. Missing values use defaults; invalid values are rejected. Branding changes appear on subsequent requests. Restart after changing the listen address or port. + +| Setting | Purpose | +|---|---| +| `site_name`, `tagline`, `welcome_message` | Text shown on the website and DSi menus. | +| `accent_colour` | Web accent in `#RRGGBB` format. | +| `logo_url` | Bundled static image or the uploaded server logo. | +| `registration_enabled`, `guest_posting` | Enable or disable account creation and guest posting. | +| `max_upload_bytes` | Maximum PPM upload size; default 2 MiB. | +| `host`, `port` | Listen address and port. These are changed through setup or the file, rather than the web form. | + +Environment overrides are available for established deployments: + +| Variable | Purpose | +|---|---| +| `REXIMEMO_PORT` | Override the configured port. | +| `REXIMEMO_HOST` | Override the configured listen address. | +| `REXIMEMO_CONFIG` | Use another settings JSON file. | +| `REXIMEMO_DB` | Use another SQLite file. PPM/mini-comment media remains in `database/Creators` and `database/Comments`. | + +## Check, back up and restore + +Use the environment's Python executable: + +```sh +.venv/bin/python manage.py check +.venv/bin/python manage.py backup +.venv/bin/python manage.py backup --output backups/before-update.zip +``` + +Windows uses `.venv\Scripts\python.exe`. The aliases `--check` and `--backup` work too. + +`check` reports the Python version, installed dependencies, settings, SQLite health, write access and listen address. An occupied port is expected if OSE is already running. + +`backup` creates an online SQLite snapshot and includes the PPMs, mini comments, static assets, custom logo and settings. Logs are omitted. The default destination is the `backups` folder. Backups contain account and IP records: keep them private. + +To restore, stop OSE, keep a copy of your current installation, then extract the backup into the OSE folder. Restore the database and settings to their configured locations if you use `REXIMEMO_DB` or `REXIMEMO_CONFIG`. Restart and run `manage.py check`. + +## Update an existing installation + +1. Stop OSE and make a backup. +2. Replace the program files, keeping `database/`, `server-settings.json` and your custom static assets. +3. Run the start script. It refreshes dependencies if required. +4. Existing databases receive the new metadata and moderation columns automatically. Existing PPMs are not re-encoded. +5. Run `manage.py setup` if you have not selected your own administrator. + +## Run as a Linux service + +`deploy/reximemo-ose.service` is an example for an installation at `/opt/reximemo-ose`. It runs as a dedicated `reximemo-ose` user. Adapt the paths to your installation. + +Create that system user and give it access to the installation and data. Create the virtual environment, install dependencies and run setup as that user before installing the unit. This avoids creating files that the service cannot later update. + +Copy the unit to `/etc/systemd/system/`, reload systemd, and enable/start `reximemo-ose.service`. View its logs with: + +```sh +sudo journalctl -u reximemo-ose.service -f +``` + +The service uses the same settings as a terminal launch. It does not configure DNS, HTTPS certificates or a NAS/auth gateway. + +## Troubleshooting + +| Problem | What to check | +|---|---| +| Python not found | Install Python 3.10 or newer and reopen the terminal. | +| Dependency installation fails | Read the package error and check your Internet connection. Run the start script again afterwards. | +| Address/port already in use | Stop the other OSE process or choose another port with setup. | +| Website works locally but DSi cannot connect | Check the listen address, local IP, firewall, proxy port and external DNS/NAS setup. | +| Default administrator no longer works | Use the administrator selected during setup. | +| Settings file error | Correct the JSON/value named by the error or restore the previous settings from a backup. | + +The format and resource reference remains in [DOCS.md](DOCS.md).