Deploy Railbase on your server

This guide covers a customer-managed Linux server. Obtain the exact supported release from your railbase.app Account. Availability in Account determines which package and architecture you can install; a development demo or CI candidate is not a customer release.

For a Mac, start with the signed installer in the installation guide. Hosting on your own VPS is On-premise/customer-hosted deployment. Railbase Cloud remains Coming soon.

1. Obtain the package through Account

Sign in to railbase.app, complete company verification and review the Railbase Product subscription. In Account, use the available installation package or the authenticated Linux repository. Each repository credential belongs to a specific authorised account and can be revoked.

After applying the repository setup commands supplied by Account:

# Debian / Ubuntu
sudo apt update
sudo apt install railbase

# Fedora / RHEL-compatible systems
sudo dnf install railbase

Use the architecture shown for your server. Keep package and repository signature verification enabled. Do not obtain the runtime from an unverified mirror or a public demo server.

2. Check the installed service and its state

The Linux package creates the railbase service account and installs the service, configuration and initial private unlock material. Its default listener is 127.0.0.1:3000.

railbase --version
sudo systemctl status railbase
curl --fail http://127.0.0.1:3000/healthz
curl --fail http://127.0.0.1:3000/readyz

Purpose	Packaged Linux location
Service configuration	/etc/railbase/railbase.env
Vault unlock file	/etc/railbase/vault-password
Data, uploaded files and runtime state	/var/lib/railbase
Installation master secret	/var/lib/railbase/.secret
Active runtime managed by the update lifecycle	/var/lib/railbase/runtime/railbase

On a fresh packaged installation, the installer creates independent secrets. If an existing Vault is present and a required secret is missing, restore the matching secret from backup; generating a replacement will not recover the data. Do not replace the package service with a second service pointing at another data folder.

3. Configure the public HTTPS address

Point your chosen hostname at the server. Keep Railbase bound to loopback and allow public access through a reverse proxy on HTTPS. For Caddy:

app.example.com {
    reverse_proxy 127.0.0.1:3000
}

Set the public origin in the existing protected service environment file:

RAILBASE_PROD=true
RAILBASE_DEV=false
RAILBASE_HTTP_ADDR=127.0.0.1:3000
RAILBASE_DATA_DIR=/var/lib/railbase
RAILBASE_VAULT_PASSWORD_FILE=/etc/railbase/vault-password
RAILBASE_PUBLIC_URL=https://app.example.com
RAILBASE_TRUSTED_PROXIES=127.0.0.1/32,::1/128
RAILBASE_ENCRYPT_STORAGE=true

Keep any other intentional settings already in that file. Then restart the service and check readiness again:

sudo systemctl restart railbase
curl --fail https://app.example.com/healthz
curl --fail https://app.example.com/readyz

RAILBASE_PUBLIC_URL must be the origin users can actually reach, including a valid certificate. Invitation links and mobile authentication depend on it. Trust only the actual reverse-proxy addresses. If you use another proxy, preserve Host and forwarded protocol information and support both streaming responses and WebSocket upgrades.

Uploaded files are encrypted by default; keep encryption enabled. The Vault password and installation master secret are different recovery requirements. Protect and back up both; neither belongs in a chat, screenshot or public script.

4. Complete the browser first-run setup

Keep access limited to the installation operator until setup is complete. Open the installation URL: a fresh installation shows its first-run form. Create the first operator using a real email and private password, and provide the first company's legal details. Alternatively, use the form's supported connection to adopt an already verified company from your Account.

The first operator is a user with installation authority. Company membership and business permissions remain separate. After the first operator exists, the first-run form must no longer create another one. Invite additional people and assign their roles through the normal workspaces.

5. Connect the Product and prove the first result

Connect the deployment through the supported Account/installation flow and verify that the intended company has the active Railbase Product entitlement. Only install additional Products that are available for that account and release.

Invite the requester and reviewer, publish the required organisation and process, and complete the first-process walkthrough. Check the request, attachment, decision and final dossier using each person's actual role. A running service and an HTTP 200 do not establish that the business workflow is ready.

For Mobile, open Connect phone on the installation sign-in page and scan the QR from a second screen. Confirm the HTTPS origin, then sign in as an existing invited user. Company choices come from that authenticated identity. A localhost address reachable on the server is not necessarily reachable from a phone.

6. Preserve recovery and update evidence

Back up /etc/railbase and the complete configured state under /var/lib/railbase, including matching secrets and external file stores where configured. Use the backup and recovery guidance and verify recovery in an isolated installation. Copying a running Vault alone is not a complete recovery test.

Use the authenticated, verified update channel and your maintenance policy. Keep the deployed version, previous recoverable state and support contacts recorded. If startup fails, inspect sudo journalctl -u railbase and the actual configuration; do not work around it by enabling DEV or replacing a missing secret.

About the shared demo

A public Railbase demonstration may deliberately run in DEV mode with synthetic people and role switching. That environment helps you explore workflows. It does not establish customer release acceptance, host your company data or provide a production configuration to copy.