Files
runicgateway.com/src/content/docs/docs/getting-started/install-the-site.mdx
wtclaude 4426d3e339
All checks were successful
PR checks / checks (pull_request) Successful in 2m10s
feat(docs): phase 14 - game-neutral core docs, an Ultima Online group, and checkTerms
PLAN.md §16, D63/D64, plus D67-D69 taken 2026-10-22.

- Core docs use core's words: a Team, a game server, the sidecar, the bridge
  plugin, the game module. Detail that belonged to Ultima Online moved into
  its pages rather than being dropped.
- New "Ultima Online" sidebar group (nine pages): an overview, Connect a
  ServUO shard, Verify the bridge, The shard connection, Client files,
  Troubleshooting, Bridge.cfg, sidecar.toml, Shard event catalog. Five moved
  URLs answer a real 301 (src/config/redirects.mjs, asserted by the served
  test).
- Getting started is game-neutral. "Connect your game server" keeps the old
  URL and hands off to each game; Rust links docs main:rust-link/INSTALL.md
  until phase 15. "Verify the whole stack" stays, neutral (D69).
- D68: GameExample.astro labels a game's real example on a core page with the
  game's name; checkTerms allows that game's words inside it.
- scripts/checkTerms.mjs, the twelfth check: 16 game words, docs pages and
  both sidebar trees, one allowlisted phrase (Discord's "Guild (server) ID").
  Wired into verify and pr-checks.yml.
- canonicalDocs grouped by game; the Rust group carries four documents.
- D67: the screenshot rule from #32 is adopted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-22 08:54:37 -05:00

141 lines
5.6 KiB
Plaintext

---
title: Install the site
description: A complete Docker Compose deployment you can copy from this page — two files, two commands.
---
import { Aside, Code, Steps } from '@astrojs/starlight/components';
import { compose, env, omittedServices } from '../../../../data/quickstart.mjs';
export const envText = env.map((e) => `${e.key}=${e.value}`).join('\n');
export const fillLines = env.filter((e) => e.fill).map((e) => `${e.key}=${e.value}`);
The site is a Docker deployment: a MariaDB container, the prebuilt application image, and
two files you write. Nothing is compiled on your host, and there is no repository to clone
— everything you need is on this page.
<Steps>
1. **Make a directory for the deployment.**
Everything below is relative to it, and the bind mounts want to exist before the
containers do — Docker creates a missing mount source as `root`, and the container user
then cannot write it.
```bash
mkdir -p runic-gateway/logs runic-gateway/brand runic-gateway/modules
cd runic-gateway
```
2. **Write `docker-compose.yml`.**
<Code code={compose} lang="yaml" title="docker-compose.yml" />
This file only ever *pulls*. There is no `build:` anywhere in it, which is deliberate:
a production host should not be able to build an image by accident.
3. **Write `.env` beside it.**
Every highlighted line must be changed before this is a real deployment. The secrets
want to be long random strings — `openssl rand -base64 36` three times is enough.
<Code code={envText} lang="ini" title=".env" mark={fillLines} />
4. **Pull and start.**
```bash
docker compose pull
docker compose up -d
```
The database comes up first; the app waits for its health check, creates its schema,
seeds defaults, creates your first admin, and starts listening.
5. **Check that it is up.**
```bash
curl -s http://localhost:3000/api/health
```
```json
{"status":"ok"}
```
If that answers, the site is running. Go to
[First run](/docs/getting-started/first-run/).
</Steps>
## What you just deployed
```
localhost:3000 ──► app (the website: API + the built React client, one process)
│
└──► db (MariaDB, no host port — only the app can reach it)
```
Four host directories and two volumes hold everything that survives a container:
| Path | What is in it |
|---|---|
| `./logs/` | `app.log`, readable from the host without `docker exec` |
| `./modules/` | Installed [modules](/docs/getting-started/install-a-game-module/). A bind mount, so placing one by hand is a supported install |
| `./brand/` | Your logo, hero and favicon, if you replace the defaults ([Branding and theming](/docs/administration/branding-and-theming/)) |
| `dbdata` volume | The database |
| `uploads` volume | Everything uploaded through the site |
<Aside type="caution" title="`restart: unless-stopped` is load-bearing">
It is not boilerplate. Installing a module needs a restart, and the admin panel offers a
button for it — that button exits the process and lets the supervisor bring it back. On a
deployment with nothing supervising the process, the button takes the site down and leaves
it down. Docker Compose is the supervisor here, and this line is what makes it one.
</Aside>
## Two variables worth reading twice
**`SECRET_ENC_KEY`** encrypts secrets at rest — OAuth client secrets, the Discord bot
token, the game module's sidecar token. In production the server **refuses to start** without it.
Changing it later does not re-encrypt anything: what was stored under the old key can no
longer be read, and every stored secret has to be entered again.
**`BOT_INTERNAL_KEY`** authenticates the internal channel between the site and the Discord
bot. The server also refuses to start in production if it is blank, left at a placeholder,
or shorter than 16 characters — even when, as here, you are not running the bot yet.
<Aside type="note" title="Both of those are set once, before the first boot">
They are not "fill in later" values. The first boot is when your admin account and the
site's defaults are written, and it will not happen at all until both are set.
</Aside>
## What this quickstart leaves out
The project's shipped Compose file has two more services. Neither is needed to boot, and
each is introduced where it is configured:
<ul>
{Object.entries(omittedServices).map(([name, why]) => (
<li key={name}><strong><code>{name}</code></strong> — {why}</li>
))}
</ul>
It also leaves out the branding, logging and session variables, which have working
defaults and their own admin screens. The full file and the full environment reference are
in the [website repository](https://gitea.whitlocktech.com/RunicGateway/website).
## Behind a reverse proxy
Not required to get started, and required before anyone else uses the site. Two settings
here are what make it correct:
- **`TRUST_PROXY=1`** tells the app to read the client's address from `X-Forwarded-For`.
Rate limiting, login backoff and the bot-scoring IP bans are all only as accurate as
that. Set it to the number of proxies in front of the app, or pin it to the proxy's
address; a blanket `true` is rejected on purpose, because it would let anyone spoof
their address by sending a header.
- **`COOKIE_SECURE=auto`** issues a `Secure` session cookie when the request arrives over
HTTPS and a plain one otherwise, so logging in works both through the proxy and directly
on the LAN while you are setting up.
Point the proxy at port 3000. Do not forward `INTERNAL_PORT` (3001) — it is the
server-to-bot channel, it is deliberately not published by the Compose file, and it must
never be reachable from outside.