Web installation guide
After starting Sayrud with binary deployment, Docker Compose, or Kubernetes, open http://server-address:2830/setup. Before installation, the home page also redirects here.
Installation has four steps: verification, database, administrator, and completion. You can change the language in the top-right corner.
Verify your identity
If no installation token is specified, the startup logs show Setup token: and an installation link containing the token. Copy the token into the page and click “Verify”. For remote deployments, replace localhost in the logged link with your actual address.
| Deployment method | Where to find logs |
|---|---|
| Foreground process | Current terminal |
| systemd | sudo journalctl -u sayrud -n 100 --no-pager |
| Docker Compose | docker compose logs --tail=100 sayrud |
| Kubernetes | kubectl -n sayrud logs deployment/sayrud --tail=100 |
If SAYRUD_SETUP_TOKEN is set, enter its value. The K8s instructions use this method; the token is in the local file used to create the Secret.
A custom token must contain at least 16 characters after removing spaces and hyphens. You can generate one with openssl rand -hex 24. Verification ignores case, spaces, and hyphens.
Unless you set a fixed token, restarting the process during installation generates a new one. Retrieve it from the latest logs. Share the token or token-bearing link only with the installer; the installation endpoints close after the administrator is created.
Configure the databases
For a new installation, enter the following:
| Service | Fields |
|---|---|
| PostgreSQL | Host, port, database name, username, password, SSL mode |
| Redis | Address in host:port format, plus an optional username and password |
Connections originate from the Sayrud process, not the computer running your browser. The Docker Compose configuration uses postgres and redis:6379; K8s uses in-cluster Service names or reachable external domains.
PostgreSQL SSL modes are “No encryption”, “Encrypted”, “Encrypted, verify CA”, and “Encrypted, verify CA and host name”. Choose the mode required by your database service. Certificate verification also requires the runtime environment to trust the relevant CA.
Click “Test connection”, check that both PostgreSQL and Redis connect successfully, then click “Save and continue”.
Create the administrator
Enter an email address, username, password, and password confirmation, then click “Complete installation”.
This creates the first system administrator and signs you in automatically. Click “Get started” to enter the application.
After installation, check that you can create projects, edit records, and upload attachments, and that configuration and uploads are persisted by your deployment. Site settings, registration, sign-in methods, and AI models can be configured in the admin console.
Provide configuration in advance
If a configuration management system supplies your connection settings, prepare sayrud.yaml in advance. The following configuration uses local storage; replace the connection password and auth.secret_key first:
postgres:
dsn: "postgres://sayrud:[email protected]:5432/sayrud?sslmode=disable"
redis:
address: "127.0.0.1:6379"
username: ""
password: ""
auth:
secret_key: "REPLACE_WITH_BASE64_KEY"
storage:
type: local
local:
path: ./data/storageGenerate auth.secret_key with this command and put the complete output in the configuration:
openssl rand -base64 32When writing a PostgreSQL URL by hand, URL-encode special characters such as @, :, and / in passwords. The wizard handles encoding for you.
Place the file at the path specified in the startup arguments. For more options, see the sample configuration. Restart the program after changing the configuration.
Troubleshooting
The installation page does not appear
If the logs show a successful startup and the database already has users, the program serves the application directly. Sign in with an existing account.
The installation token is invalid
Check whether the process restarted during installation. If SAYRUD_SETUP_TOKEN is not set, use the token from the latest logs. On K8s, check that the Pod uses the expected Secret and keep one replica during initial installation. Repeated incorrect tokens trigger rate limiting; check the token before trying again.
The database connection test fails
Check that the database exists, credentials are correct, and the application host or Pod can reach it. Inside a container, 127.0.0.1 refers to that container. If the connection test succeeds but saving fails, check schema migration permissions too.
A new installation cannot take over a database that already has users. To restore an existing instance, restore its original configuration, key, and uploaded files, then connect to its database through normal startup rather than the database setup step.
Saving configuration fails with a permission error
The wizard writes a temporary file in the configuration directory before committing it as sayrud.yaml, so the directory must be writable. Check for read-only mounts, ConfigMaps, Secrets, or a mismatch between the process UID/GID and volume ownership. The Docker and K8s images use 10001:10001.
Configuration was saved but a restart is required
Check the service logs, resolve the subsequent initialization failure, and restart with the same configuration path. The saved configuration will be read again; there is no need to delete it and reinstall.
The installation page returns after recreating a container
Check that the configuration directory is mounted at /home/app/config, that you are using the original PostgreSQL database, and that the Compose project name or K8s PVC has not changed. Recover the original configuration and data before proceeding with a new installation.