docs: getting started doc
This commit is contained in:
Florian Sylvain committed
1 parent
ed0686085a
commit
63b671c6f3
2 files changed
+185
No files matched your search
@@ -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 |
|
||||
|
||||
@@ -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_<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.
|
||||
Reference in new issue
Block a user