RenewCMS/docs/getting-started.md

# 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_<version>_<os>_<arch>`:

| 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.