diff --git a/README.md b/README.md index 35b473a..13d2447 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ task dev # API with hot reload + Vite HMR → http://localhost:51 | Doc | Contents | |---|---| +| [docs/getting-started.md](docs/getting-started.md) | Set up an instance: download the binary or start Docker, fill the settings, HTTPS, first login | | [docs/development.md](docs/development.md) | Dev setup, how Vite and the API fit together, tests, lint, `task` commands | | [docs/deployment.md](docs/deployment.md) | Building release binaries, running as a service, HTTPS, backups, upgrades | | [docs/docker.md](docs/docker.md) | Running RenewCMS in Docker: image, Compose, data volume, backups, reverse proxy, tags, upgrades, publishing | diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..af1bbe7 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,184 @@ +# Getting started + +Get a RenewCMS site running in about ten minutes. You need no Go, Node or Bun: RenewCMS is one ready-made program, or one Docker image. + +Pick one way to run it: + +- [Option A: Docker](#option-a-docker), the shortest path on any machine with Docker. +- [Option B: the binary with systemd](#option-b-binary-and-systemd), for a Linux server. + +Both need the same few settings, listed first. + +## What you need + +- A server or computer. Linux, macOS and Windows are supported, on amd64 or arm64. +- The public address of your site, such as `https://cms.example.com`. This is `PUBLIC_URL`. +- An SMTP account for the emails RenewCMS sends (account verification, invitations). Your mail provider gives you the host, port, login and password. +- A domain name and HTTPS for a real site (see [Put HTTPS in front](#put-https-in-front)). For a quick trial on your own computer, `http://localhost:8080` is enough. + +## The settings + +Four groups of settings are required. Everything else has a sensible default. + +| Setting | Example | Meaning | +|---|---|---| +| `PUBLIC_URL` | `https://cms.example.com` | Address visitors use to reach the site. | +| `JWT_SECRET` | output of `openssl rand -hex 32` | Long random secret that signs logins. Keep it private and never change it casually: changing it signs everyone out. | +| `SMTP_HOST`, `SMTP_PORT` | `smtp.example.com`, `465` | Your mail server. | +| `SMTP_LOGIN`, `SMTP_PASSWORD`, `SMTP_SENDER` | `noreply@example.com`, `…`, `noreply@example.com` | Mail account and the From address. | + +The server stops at startup and names the missing setting if one is absent. Every available setting is documented in [configuration.md](configuration.md). + +## Option A: Docker + +Requires Docker with Compose v2. + +1. Create a folder and download the two files: + + ```sh + mkdir renewcms && cd renewcms + curl -fsSLO https://git.floriansylvain.fr/fsylvain/RenewCMS/raw/branch/main/docker-compose.yml + curl -fsSL https://git.floriansylvain.fr/fsylvain/RenewCMS/raw/branch/main/docker.env.example -o docker.env + ``` + +2. Edit `docker.env` and set `PUBLIC_URL`, the `SMTP_*` values and `JWT_SECRET`. Generate the secret with: + + ```sh + openssl rand -hex 32 + ``` + + For a trial on your own computer over plain HTTP, also set `ENVIRONMENT=development` and `PUBLIC_URL=http://localhost:8080`. Without this, browsers refuse the login cookie over `http://`. Use `production` (the default) only behind HTTPS. + +3. Start it: + + ```sh + docker compose up -d + ``` + +4. Check it: `curl http://localhost:8080/healthz` answers `ok`. Open `http://localhost:8080` in your browser. + +Your data (database and uploaded images) lives in the `renewcms-data` volume, so it survives restarts and upgrades. To upgrade later: + +```sh +docker compose pull && docker compose up -d +``` + +More in [docker.md](docker.md): pinning a version, MySQL or PostgreSQL, backups. + +## Option B: binary and systemd + +This is for a Linux server with systemd. On macOS, or on Windows, you can run the same binary from a terminal after setting the same variables. + +### 1. Download + +Open the [releases page](https://git.floriansylvain.fr/fsylvain/RenewCMS/releases) and pick the file for your platform. The names look like `renewcms___`: + +| Platform | File ends with | +|---|---| +| Linux, Intel or AMD | `_linux_amd64` | +| Linux, ARM (Raspberry Pi 4/5, ARM servers) | `_linux_arm64` | +| macOS, Intel | `_darwin_amd64` | +| macOS, Apple Silicon | `_darwin_arm64` | +| Windows | `_windows_amd64.exe` or `_windows_arm64.exe` | + +Download and install it, replacing `v3.7.2-beta` with the version you want and `linux_amd64` with your platform: + +```sh +curl -fsSL -o renewcms https://git.floriansylvain.fr/fsylvain/RenewCMS/releases/download/v3.7.2-beta/renewcms_v3.7.2-beta_linux_amd64 +sudo install -D -m 755 renewcms /opt/renewcms/renewcms +/opt/renewcms/renewcms --version +``` + +### 2. Create a service user and folders + +```sh +sudo useradd --system --home /var/lib/renewcms --shell /usr/sbin/nologin renewcms +sudo install -d -o renewcms -g renewcms /var/lib/renewcms +sudo install -D -m 600 /dev/null /etc/renewcms/renewcms.env +``` + +### 3. Fill the settings + +Open `/etc/renewcms/renewcms.env` with your editor (`sudo nano /etc/renewcms/renewcms.env`) and paste: + +```sh +ENVIRONMENT=production +PUBLIC_URL=https://cms.example.com +PORT=8080 +DB_FILE=/var/lib/renewcms/renewcms.db +UPLOAD_DIR=/var/lib/renewcms/uploads +JWT_SECRET=paste-the-output-of-openssl-rand-hex-32 +SMTP_HOST=smtp.example.com +SMTP_PORT=465 +SMTP_LOGIN=noreply@example.com +SMTP_PASSWORD=your-smtp-password +SMTP_SENDER=noreply@example.com +``` + +### 4. Create the service + +Create `/etc/systemd/system/renewcms.service`: + +```ini +[Unit] +Description=RenewCMS +After=network-online.target +Wants=network-online.target + +[Service] +User=renewcms +Group=renewcms +WorkingDirectory=/var/lib/renewcms +EnvironmentFile=/etc/renewcms/renewcms.env +ExecStart=/opt/renewcms/renewcms +Restart=on-failure +TimeoutStopSec=15 +NoNewPrivileges=true +ProtectSystem=strict +ProtectHome=true +PrivateTmp=true +ReadWritePaths=/var/lib/renewcms + +[Install] +WantedBy=multi-user.target +``` + +### 5. Start it + +```sh +sudo systemctl daemon-reload +sudo systemctl enable --now renewcms +curl -fsS http://localhost:8080/healthz +``` + +`ok` means it is running. If not, read the logs with `journalctl -u renewcms -n 50`: a missing setting is named there. + +To upgrade, download the new file, then `sudo install -m 755 renewcms /opt/renewcms/renewcms && sudo systemctl restart renewcms`. The database is migrated automatically at startup. Back up `/var/lib/renewcms` first. Optionally, [browser updates](deployment.md#browser-updates) let the owner upgrade from the Settings page. + +## Put HTTPS in front + +In production the login cookie is `Secure`, so the site must be served over HTTPS. Keep RenewCMS on `localhost:8080` and let a reverse proxy handle the certificate. With [Caddy](https://caddyserver.com), certificates are automatic. In `/etc/caddy/Caddyfile`: + +```caddyfile +cms.example.com { + reverse_proxy localhost:8080 { + header_up X-Real-IP {remote_host} + } +} +``` + +Then `sudo systemctl reload caddy`. Point your domain's DNS at the server first. For nginx, and for the proxy-related settings (`TRUSTED_PROXIES`), see [deployment.md](deployment.md#4-put-https-in-front). + +## First login + +1. Open your `PUBLIC_URL` in a browser. +2. Create your account. The first account created becomes the **Owner** of the site. +3. Confirm your email with the message RenewCMS sends. If it never arrives, check the `SMTP_*` settings and the logs. +4. From there, invite teammates and start writing. + +## Where to go next + +- [configuration.md](configuration.md): every setting, including MySQL, PostgreSQL and S3 storage. +- [docker.md](docker.md): Docker details, backups and versions. +- [deployment.md](deployment.md): browser updates, reverse proxy variants, backups. +- [api.md](api.md): reading your content from your own website.