Skip to content

πŸ“š The open-source, offline-first Notion, Obsidian & Confluence alternative. Advanced Markdown, multi-tenant teams, OIDC/SSO, and local S3 backups. Deploy in one command.

13.0 KB
Raw Blame

title: Environment variables description: Complete reference of the environment variables supported by Alexandrie. navigation: icon: i-lucide-sliders-horizontal

This page provides a concise reference of the environment variables supported by Alexandrie.

Only variables documented here and in .env.example are officially supported.

The .env file is placed next to docker-compose.yml. Some backend-specific variables must also be passed to the backend service in docker-compose.yml.

Public URLs & Global Access

Variable Accepted Values Description
FRONTEND_URL URL Public URL of the frontend application, used by clients and browsers.
API_URL URL Public URL of the backend API.
CDN_URL URL Public URL of the S3-compatible object storage (RustFS).
CDN_ENDPOINT Path Path prefix under which objects are exposed. Final object URLs are built as <CDN_URL><CDN_ENDPOINT><object-path>.

CDN_ENDPOINT is normally /alexandrie/ when using the default bucket. If you change the bucket name or expose storage through a reverse-proxy path, make sure the value matches your setup.

For example:

FRONTEND_URL=https://wiki.example.com
API_URL=https://api.example.com
CDN_URL=https://files.example.com
CDN_ENDPOINT=/alexandrie/

Application Feature Flags

Variable Accepted Values Default Description
CONFIG_DISABLE_LANDING true / false false Disables the landing page and redirects users to the login page.
CONFIG_DISABLE_SIGNUP true / false false Disables new user registrations in both the frontend and backend.
CONFIG_DISABLE_NATIVE_LOGIN true / false false Disables native username/password authentication. Useful when authentication is handled through OIDC.
CONFIG_HIDE_NATIVE_LOGIN_FORM true / false false Hides the native username/password login form without disabling the authentication method itself. Useful with external authentication.
CONFIG_OIDC_PROVIDER_AUTO_REDIRECT Provider name / empty Empty Automatically redirects users from the login page to the OIDC provider whose configured provider name matches this value.

For example, a deployment using OIDC exclusively can use:

CONFIG_DISABLE_NATIVE_LOGIN=true
CONFIG_HIDE_NATIVE_LOGIN_FORM=true
CONFIG_OIDC_PROVIDER_AUTO_REDIRECT=Google

Backend API β€” Runtime & Security

Variable Accepted Values Description
BACKEND_EXTERNAL_PORT Port number Port exposed on the host for the backend API.
COOKIE_DOMAIN Domain, no protocol Domain scope for authentication cookies. It must be the highest common domain shared by the frontend and backend.
ALLOW_UNSECURE true / false Allows HTTP connections. Use true for local/development setups and false in production when HTTPS is configured.
JWT_SECRET String Secret used to sign JWT tokens. Use a long random value in production. Changing it invalidates existing sessions.
ADMIN_ACCOUNTS Comma-separated user IDs List of user IDs that have administrator privileges.

For example, if the frontend and backend are:

https://wiki.example.com
https://api.example.com

use:

COOKIE_DOMAIN=example.com

Do not include http:// or https:// in COOKIE_DOMAIN.

Database β€” MySQL

Variable Accepted Values Description
MYSQL_EXTERNAL_PORT Port number Port exposed on the host for MySQL.
MYSQL_DATABASE String Name of the default database created for Alexandrie.
MYSQL_USER String Username of the default Alexandrie database user.
MYSQL_PASSWORD String Password of the default Alexandrie database user.
MYSQL_ROOT_PASSWORD String Password of the MySQL root user.

Example:

MYSQL_EXTERNAL_PORT=3307
MYSQL_DATABASE=alexandrie
MYSQL_USER=alexandrie
MYSQL_PASSWORD=<strong-password>
MYSQL_ROOT_PASSWORD=<strong-root-password>

The application should use the normal Alexandrie database user rather than the MySQL root account.

Object Storage β€” RustFS / S3

RustFS service

Variable Accepted Values Description
RUSTFS_EXTERNAL_PORT Port number Port exposed on the host for RustFS.
RUSTFS_ACCESS_KEY String Access key used by the S3-compatible API.
RUSTFS_SECRET_KEY String Secret key used by the S3-compatible API.
MINIO_BUCKET String Main bucket used by Alexandrie. The backend also creates a <bucket>-backups bucket.

Example:

RUSTFS_EXTERNAL_PORT=9000
RUSTFS_ACCESS_KEY=<access-key>
RUSTFS_SECRET_KEY=<secret-key>
MINIO_BUCKET=alexandrie

MINIO_BUCKET should match the bucket represented by CDN_ENDPOINT.

S3 / TLS

Variable Accepted Values Default Description
MINIO_SECURE true / false true Controls whether the backend connects to the S3 endpoint using HTTPS. Must match how the endpoint is exposed.
MINIO_CA_PATH File path β€” Path to a custom CA certificate in PEM format. Required when the S3 endpoint uses a certificate signed by a private/internal CA.
MINIO_INSECURE_TLS true / false false Disables TLS certificate verification while keeping HTTPS enabled. Intended for debugging/local testing and not recommended for production.

Use:

MINIO_SECURE=true

for HTTPS, or:

MINIO_SECURE=false

for an HTTP S3 endpoint.

When using Docker, MINIO_CA_PATH points to a file inside the backend container. The CA certificate must therefore be mounted into that container through docker-compose.yml.

MINIO_INSECURE_TLS=true keeps the connection encrypted but disables certificate and hostname verification.

Email β€” SMTP

SMTP is optional and is used for password reset emails. Leave these variables empty to disable email features.

Variable Accepted Values Description
SMTP_HOST Hostname SMTP server hostname.
SMTP_MAIL Email address Email account used to send messages.
SMTP_PASSWORD String Password for the SMTP account.
SMTP_MAIL_FROM Email address Optional sender address. If omitted, SMTP_MAIL is used.

Example:

SMTP_HOST=smtp.example.com
[email protected]
SMTP_PASSWORD=<password>
[email protected]

Frontend β€” Nuxt

Variable Accepted Values Description
FRONTEND_EXTERNAL_PORT Port number Port exposed on the host for the frontend container.

Example:

FRONTEND_EXTERNAL_PORT=8200

In a production deployment this port is normally accessed only by the reverse proxy.

Advanced Backend Configuration

Variable Accepted Values Description
CONFIG_PATH File path Path to a custom config.toml file used by the backend.

Example:

CONFIG_PATH=./config.toml

A custom config.toml can be used for backend settings that are not exposed through environment variables, such as default values, logging levels, and supported files.

The file must follow the same structure as the default backend configuration.

OIDC Integration

Alexandrie supports up to 10 OIDC providers.

Replace {i} with a number from 1 to 10.

Variable Accepted Values Description
OIDC_{i}_CONFIG_URL URL OpenID Connect configuration endpoint, normally the provider's .well-known/openid-configuration URL.
OIDC_{i}_CLIENT_ID String Client ID issued by the OIDC provider.
OIDC_{i}_CLIENT_SECRET String Client secret issued by the OIDC provider.
OIDC_{i}_PROVIDER_NAME String Display name of the provider, for example Google, Discord, or Microsoft.

Example:

OIDC_1_CONFIG_URL=https://accounts.example.com/.well-known/openid-configuration
OIDC_1_CLIENT_ID=<client-id>
OIDC_1_CLIENT_SECRET=<client-secret>
OIDC_1_PROVIDER_NAME=Example

The OIDC provider must be configured with the following redirect URI:

https://your-alexandrie-frontend/login/oidc/callback

When using Docker Compose, these variables must be passed to the backend service. For example:

environment:
  OIDC_1_CONFIG_URL: ${OIDC_1_CONFIG_URL}
  OIDC_1_CLIENT_ID: ${OIDC_1_CLIENT_ID}
  OIDC_1_CLIENT_SECRET: ${OIDC_1_CLIENT_SECRET}
  OIDC_1_PROVIDER_NAME: ${OIDC_1_PROVIDER_NAME}

Quick Reference

For a typical production deployment, the main variables are:

# Public URLs
FRONTEND_URL=https://wiki.example.com
API_URL=https://api.example.com
CDN_URL=https://files.example.com
CDN_ENDPOINT=/alexandrie/

# Authentication & security
COOKIE_DOMAIN=example.com
ALLOW_UNSECURE=false
JWT_SECRET=<strong-random-secret>
ADMIN_ACCOUNTS=

# MySQL
MYSQL_DATABASE=alexandrie
MYSQL_USER=alexandrie
MYSQL_PASSWORD=<strong-password>
MYSQL_ROOT_PASSWORD=<strong-root-password>

# RustFS / S3
RUSTFS_ACCESS_KEY=<access-key>
RUSTFS_SECRET_KEY=<secret-key>
MINIO_BUCKET=alexandrie
MINIO_SECURE=true

# Optional SMTP
SMTP_HOST=
SMTP_MAIL=
SMTP_PASSWORD=
SMTP_MAIL_FROM=

Important notes

  • Only variables documented on this page and in .env.example are officially supported.
  • Keep secrets such as JWT_SECRET, database passwords, S3 credentials, SMTP passwords, and OIDC client secrets out of Git.
  • COOKIE_DOMAIN must not contain a protocol.
  • MINIO_SECURE must match the protocol used by the S3 endpoint.
  • Custom CA certificates must be available inside the backend container when using Docker.
  • MINIO_INSECURE_TLS should only be used for temporary debugging or local testing.
  • For production deployments, use HTTPS and set ALLOW_UNSECURE=false.