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, the shortest path on any machine with Docker.
• Option B: the binary with 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). 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.

Option A: Docker

Requires Docker with Compose v2.

1. Create a folder and download the two files:

   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:

   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:

   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:

docker compose pull && docker compose up -d

More in 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 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:

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

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:

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:

[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

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 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, certificates are automatic. In /etc/caddy/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.

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: every setting, including MySQL, PostgreSQL and S3 storage.
• docker.md: Docker details, backups and versions.
• deployment.md: browser updates, reverse proxy variants, backups.
• api.md: reading your content from your own website.