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.

6.3 KB
Raw Blame

title: Configuration reference description: Alexandrie's main environment variables. navigation: icon: i-lucide-settings-2

Copy .env.example to .env, then change the necessary values. Never commit the final .env file.

Configuration & options

The following sections describe the main environment variables used by Alexandrie. For a complete list of all available variables, see Environment variables.

1. Public URLs & Global Access

FRONTEND_URL=http://localhost:8200
API_URL=http://localhost:8201
CDN_URL=http://localhost:9000

CDN_ENDPOINT=/alexandrie/

These variables define how clients (browsers) reach your services.

  • FRONTEND_URL: The public URL for the frontend service.
  • API_URL: The public URL for the backend API service.
  • CDN_URL: The public URL for the object storage service (RustFS).
  • CDN_ENDPOINT: The path prefix under which files are exposed. You probably want to keep this as /alexandrie/ to match the bucket name, change it only if you changed the bucket name or if you have configured a reverse proxy path.
    Final URL are constructed as: <CDN_URL><CDN_ENDPOINT><object-path>
    If you have a problem with files URL just open devtools in your browser and check the actual URL used to load files and then adjust these variables accordingly.

2. Application Feature Flags

CONFIG_DISABLE_LANDING=false
CONFIG_DISABLE_SIGNUP=false
CONFIG_DISABLE_NATIVE_LOGIN=false
CONFIG_OIDC_PROVIDER_AUTO_REDIRECT=""
CONFIG_HIDE_NATIVE_LOGIN_FORM=false

These variables control specific features of the application (useful for private deployments, internal tools etc.).

  • CONFIG_DISABLE_LANDING: If set to true, the landing page is disabled, and users are redirected to the login page. The default is false.
  • CONFIG_DISABLE_SIGNUP: If set to true, new user registrations are disabled (in frontend + backend for security). The default is false.
  • CONFIG_DISABLE_NATIVE_LOGIN: If set to true, the native username/password login method is disabled. This is useful if you want to enforce OIDC or other external authentication methods. The default is false.
  • CONFIG_HIDE_NATIVE_LOGIN_FORM: If set to true, the native username/password login method is hidden. This is useful if you want to enforce OIDC or other external authentication methods but without setting up CONFIG_OIDC_PROVIDER_AUTO_REDIRECT. The default is false. Recommended to use in conjunction with CONFIG_DISABLE_NATIVE_LOGIN.
  • CONFIG_OIDC_PROVIDER_AUTO_REDIRECT: Provide a string that matches the provider name of one of your OIDC providers, if provided the user is automatically redirected to the OIDC login when landing on the login page.

3. Backend API β€” Runtime & Security

BACKEND_EXTERNAL_PORT=8201
COOKIE_DOMAIN=localhost:8200
ALLOW_UNSECURE=true
JWT_SECRET=your-secure-jwt-secret-key-change-this-in-production
ADMIN_ACCOUNTS=id1,id2,id3

These variables configure the backend API service.

  • BACKEND_EXTERNAL_PORT: The port exposed on your host machine for the Backend API service.
  • COOKIE_DOMAIN (IMPORTANT): This variable defines where authentication cookies are valid.
    It should match with the common domain used by both frontend and backend services.
    Example: If your frontend is at frontend.yourdomain.com and your backend API is at api.yourdomain.com, then set COOKIE_DOMAIN=yourdomain.com.
    Rules:
    • Must match with the highest common domain between the frontend and the backend. See #286 for more details.
    • Must NOT include protocol (http:// or https://)
    • If misconfigured, login will appear to work but users will be instantly logged out
  • ALLOW_UNSECURE: If set to true, HTTP connections are allowed (useful for local and dev). In production, it is recommended to set this to false to enforce HTTPS.
  • JWT_SECRET: Secret key used to sign JWT tokens. You should change this to a random long string correcly generated (with openssl or similar) in production for security. Changing this value will invalidate all existing sessions.
  • ADMIN_ACCOUNTS: Comma-separated list of user IDs that should have admin privileges (e.g., 1,2,3). Optional.

4. Database β€” MySQL

MYSQL_EXTERNAL_PORT=3307
MYSQL_DATABASE=alexandrie
MYSQL_USER=alexandrie
MYSQL_PASSWORD=password
MYSQL_ROOT_PASSWORD=rootpassword

These variables configure the MySQL database service.

  • MYSQL_EXTERNAL_PORT: The port exposed on your host machine for the MySQL service.
  • MYSQL_DATABASE: The name of the default database created for Alexandrie.
  • MYSQL_USER: The username for the default Alexandrie database user.
  • MYSQL_PASSWORD: The password for the default Alexandrie database user.
  • MYSQL_ROOT_PASSWORD: The password for the MySQL root user.

5. Object Storage β€” S3 (RustFS / MinIO-compatible) (optional, leave empty to disable)

RUSTFS_EXTERNAL_PORT=9000

RUSTFS_ACCESS_KEY=alexandrie-key
RUSTFS_SECRET_KEY=alexandrie-secret

MINIO_BUCKET=alexandrie

These variables configure the RustFS object storage service.

  • RUSTFS_EXTERNAL_PORT: The port exposed on your host machine for the RustFS service.
  • RUSTFS_ACCESS_KEY: The access key for the RustFS S3-compatible API.
  • RUSTFS_SECRET_KEY: The secret key for the RustFS S3-compatible API.
  • MINIO_BUCKET: The name of the default bucket created for Alexandrie. Note that this bucket name should match the CDN_ENDPOINT variable in the backend configuration. By default, it is set to alexandrie and the backend will create alexandrie and alexandrie-backups buckets.

6. Email β€” SMTP (optional)

SMTP_HOST=
SMTP_MAIL=
SMTP_PASSWORD=
SMTP_MAIL_FROM= # Optional

Used only for password reset emails. Leave empty to disable email features (default).

  • SMTP_HOST: The SMTP server host.
  • SMTP_MAIL: The email address used to send emails.
  • SMTP_PASSWORD: The password for the SMTP email account.
  • SMTP_MAIL_FROM The email adress used to send messages (optional, default same as SMTP_MAIL)

7. Frontend β€” Nuxt

FRONTEND_EXTERNAL_PORT=8200

The port exposed on the host for the frontend container.

In production, this is usually only accessed by a reverse proxy.

Production Deployment Notes

In production, you should:

  • NOT expose MySQL or RustFS directly
  • Use a reverse proxy (Nginx, Traefik, Caddy)
  • Terminate HTTPS at the proxy