Deploy Alexandrie

Deploy and Host Alexandrie with Railway

Alexandrie is a self-hostable Markdown note-taking and knowledge-base application. This community template deploys Alexandrie v8.14.0 with MySQL, RustFS object storage, and a Caddy gateway. Railway supplies the HTTPS domain automatically: no custom domain, DNS configuration, registry account, or manually generated infrastructure credentials are required.

About Hosting Alexandrie

Five services run in one Railway environment. Only the Caddy gateway has a public domain. The frontend, backend, MySQL, and RustFS communicate over Railway private networking. MySQL data and uploaded files have separate persistent volumes. Passwords, S3 credentials, and the JWT signing secret are generated independently for every installation; dependent services use reference variables.

The first deployment may take a few minutes. Services start together; the backend's ALWAYS restart policy lets it retry initialization while the database and object storage become ready. The upstream backend image is distroless, so this template preserves its original entrypoint instead of assuming a shell exists. An initial dependency-connection error can be transient; continued errors after storage is ready need investigation.

Common Use Cases

• A personal Markdown notebook with attachments and image hosting.
• A small team's internal knowledge base.
• Student notes and research collections.
• A self-hosted documentation workspace without custom-domain setup.

Dependencies for Alexandrie Hosting

RustFS is a release candidate, not a stable 1.0 release. This is a single-node configuration, not high availability. Plan for backups and evaluate suitability for important data.

The MySQL service includes the official Railway template's database-panel connection aliases. Alexandrie itself uses a dedicated alexandrie database user, not root. The administrative root credential is retained only for database administration/Railway's Data panel.

Deployment Dependencies

• Alexandrie source and documentation
• Alexandrie v8.14.0
• RustFS
• Caddy
• Railway volumes and backups

First Deployment and Account Bootstrap

1. Deploy the template with its defaults. Wait for all five services to reach SUCCESS and for the frontend to load through the gateway domain.
2. Open the gateway URL and visit /signup to create your own account. The template does not create a permanent user or a shared default password.
3. For administrator access, log in, open /api/users/@me on the same gateway domain, and copy result.id. Set backend ADMIN_ACCOUNTS to that ID and redeploy the backend. For multiple admins, use comma-separated IDs. Log out and back in after promotion.
4. If the instance should be closed, set backend CONFIG_DISABLE_SIGNUP=true. Ensure both backend and frontend redeploy; the frontend signup-page flag references the backend variable. Existing accounts continue to work.
5. Enable two-factor authentication in your account settings and configure backups before keeping important data.

The first signup is not automatically made an administrator. Do not disable signup before creating your own account, or disable native login before testing a working OIDC provider.

Optional Email and SSO

SMTP is deliberately not required. Password-reset emails are unavailable until you add these backend variables:

• SMTP_HOST
• SMTP_MAIL
• SMTP_PASSWORD
• Optional SMTP_MAIL_FROM

Use credentials from your email provider; infrastructure secret generators cannot create valid SMTP credentials. OIDC can be configured later using Alexandrie's OIDC_1_CONFIG_URL, OIDC_1_CLIENT_ID, OIDC_1_CLIENT_SECRET, and OIDC_1_PROVIDER_NAME variables. Its callback is https://YOUR_GATEWAY_HOSTNAME/login/oidc/callback; replace YOUR_GATEWAY_HOSTNAME with the generated gateway hostname.

Implementation Details

The gateway preserves the original request path and host, and forwards the HTTPS protocol/port from Railway's TLS-terminated ingress:

• GET /_health returns 200.
• /api and /api/* proxy to the private backend.
• /alexandrie/* proxies to RustFS for public uploaded files.
• /alexandrie-backups/* proxies to RustFS for signed backup downloads.
• Everything else proxies to the private frontend.

The backup bucket remains private: routing its path does not grant anonymous access. RustFS validates the signed requests. The console is disabled and no route exposes its port. Caddy's admin API is also disabled.

/_health is gateway liveness, not an end-to-end database readiness check. RustFS uses /health; the frontend uses /login. The backend does not expose an unauthenticated HTTP 200 readiness endpoint in this release. Confirm application readiness by loading the frontend and exercising the authenticated API.

All public application URLs derive from gateway.RAILWAY_PUBLIC_DOMAIN; there is no hardcoded installation hostname. Keep COOKIE_DOMAIN as the hostname only and ALLOW_UNSECURE=false.

Storage, Privacy, and Backups

• Uploaded objects in the main alexandrie bucket are publicly readable by URL. Do not treat an unguessable image URL as private access control.
• Application backup archives are stored in alexandrie-backups, accessed through expiring signed URLs, and configured for 24-hour expiration.
• Application exports are not a replacement for database and object-volume backups. Enable Railway backups for both volumes and test restoration. Scheduled platform backups are not automatically enabled by this template.
• Restoring an application export uses Alexandrie's import UI; platform disaster recovery restores the MySQL and RustFS volumes consistently.
• Deleting a volume can permanently destroy data. Increasing volume capacity and backups incur Railway charges.
• Default application limits are approximately 20 MB per upload and 1 GiB of uploads per user; advanced limits require a custom backend config.toml via CONFIG_PATH.

Do not change MINIO_BUCKET, the CDN endpoint, or the gateway bucket routes independently. Merely changing a MySQL password environment variable after first initialization does not rotate the password stored inside MySQL.

Versions, Resources, and Updates

Image auto-updates are disabled. App images use explicit release tags; MySQL, RustFS, and Caddy additionally use immutable digests. Review and test upgrades deliberately. Never point an older MySQL image at data initialized by a newer major version.

Five running services and two persistent volumes incur normal Railway usage charges. CPU/RAM use depends on traffic, uploads, and database activity; no fixed monthly price is promised. MySQL's buffer pool is set to 256 MB for a small instance. This template does not require a separate paid external service or an owned domain.

Why Deploy Alexandrie on Railway?

Railway provides the generated HTTPS domain, private service networking, persistent storage, deployment logs, and resource controls in one project. This template connects those pieces with safe per-install credentials and pinned images, while keeping account ownership and future upgrade decisions with the operator.