Skip to content

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 methodWhere to find logs
Foreground processCurrent terminal
systemdsudo journalctl -u sayrud -n 100 --no-pager
Docker Composedocker compose logs --tail=100 sayrud
Kuberneteskubectl -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:

ServiceFields
PostgreSQLHost, port, database name, username, password, SSL mode
RedisAddress 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:

yaml
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/storage

Generate auth.secret_key with this command and put the complete output in the configuration:

sh
openssl rand -base64 32

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