Skip to content

Configuration file

Apleno Server is configured with environment variables, either real environment variables (as used under Docker, or set via systemd/Task Scheduler) or a .env file placed next to the apleno-server executable. Any changes require Apleno Server to be restarted.

A .env file is a plain text file with one KEY=value per line, for example:

PORT=8080
ROOT=https://apleno.example.com
HTTPS=false

A real environment variable always takes priority over the same key in .env, which lets you override a .env value for a single run without editing the file (useful in Docker, where .env isn't normally used at all, see the Docker guide).

Upgrading from an older version? See config.yml below

Older versions of Apleno Server were configured with a config.yml file instead. config.yml still works, but is deprecated. See Legacy: config.yml at the bottom of this page.

Settings

Legacy config.yml key Environment variable Description
port PORT The HTTP port of the server. 80 is the default HTTP port.
root ROOT The root URL of your server.
sessionSecret SESSION_SECRET Secret used to sign session cookies. Leave empty and Apleno Server will generate and remember one on first start.
trustedProxies TRUSTED_PROXIES How the real visitor IP is resolved. Empty, false or none trusts nothing (Apleno Server is the public edge); loopback (the default) trusts a reverse proxy running on the same host; a number trusts that many proxy hops; a comma-separated list of IPs/CIDRs trusts those specific upstream proxies.
https HTTPS true if you want HTTPS to be active.
httpsPort HTTPS_PORT HTTPS port of the server. 443 is the default HTTPS port.
httpsKey HTTPS_KEY Path to the key file of the HTTPS certificate.
httpsCert HTTPS_CERT Path to the certificate for HTTPS.
smtpHost SMTP_HOST SMTP server hostname. See configuring SMTP.
smtpPort SMTP_PORT SMTP port. Defaults to 587.
smtpSecure SMTP_SECURE Use implicit TLS. Typically true for port 465, false for STARTTLS on port 587.
smtpUser SMTP_USER SMTP auth username.
smtpPassword SMTP_PASSWORD SMTP auth password.
smtpFrom SMTP_FROM Default "From" address for outgoing mail.
authAzureAD AZURE Set to true if you want Azure AD authentication.
authAzureADClientID AZURE_CLIENT_ID The client ID of your Azure AD App.
authAzureADClientSecret AZURE_CLIENT_SECRET The secret key of your Azure AD App.
authAzureADResource AZURE_RESOURCE Resource of your Azure AD App. Can be empty.
authAzureADTenant AZURE_TENANT The tenant name of your Azure AD App. Generally in the company.onmicrosoft.com format.
authAzureADCommonEndpoint AZURE_COMMON_ENDPOINT true if you want to use the generic, multi-domain Azure login page. Generally set to false.
authOIDC OIDC Set to true if you want OIDC authentication (Okta, Keycloak, Google Workspace, or any standards-compliant provider).
authOIDCIssuer OIDC_ISSUER Issuer URL of your OIDC provider, e.g. https://accounts.example.com.
authOIDCClientId OIDC_CLIENT_ID The client ID of your OIDC application.
authOIDCClientSecret OIDC_CLIENT_SECRET The client secret of your OIDC application.
authOIDCDisplayName OIDC_DISPLAY_NAME Label shown on the sign-in button. Defaults to SSO.
authOIDCGroupsClaim OIDC_GROUPS_CLAIM Claim name to read group membership from, for group-based access rules. Defaults to groups.
authOIDCScopes OIDC_SCOPES Extra scopes to request from the provider, space-separated, on top of the defaults.

Root URL

The root URL setting might be a domain name like http://example.com or an IP like http://192.168.10.3, without ending /.

  • If the port is different than 80, append the port to the url separated with a :. For example http://example.com:8080.
  • Finally, if you have enabled HTTPS, don't forget to put https instead of http.

HTTPS parameters

See our guide on how to enable HTTPS.

Editing the .env file

Linux

The easiest way is to use the nano tool:

# nano /opt/apleno/.env

If the file does not exist yet, create it in the same folder as the apleno-server executable.

Windows

Go to the Apleno Server folder. If a .env file does not already exist there, create a new text file and name it .env (make sure Windows Explorer isn't appending a hidden .txt extension ; enable "File name extensions" in the View tab to check). Right click it and choose Open with..., then select Notepad.

When the file is open, add or change settings according to the table above, one KEY=value per line, then save and restart Apleno Server.

Legacy: config.yml

Warning

config.yml support is deprecated and will be removed in a future version. New installs should use a .env file as described above. This section only applies to installs upgrading from an older version that already have a config.yml.

Older versions of Apleno Server were configured with a config.yml file (using the "Legacy config.yml key" column of the table above) instead of environment variables. If Apleno Server finds a config.yml file at startup, it automatically:

  1. Converts every setting found in it into the matching environment variable;
  2. Saves those into data/generated.env (see below);
  3. Renames config.yml to config.yml.old, so this only ever happens once.

This migration is one-way and silent (aside from a log line). You do not need to do anything yourself. If you were relying on config.yml, your settings keep working exactly as before; you can just ignore config.yml.old or delete it once you've confirmed the server still starts correctly.

data/generated.env

data/generated.env is a file Apleno Server manages itself. It is not meant to be edited by hand. It holds values the server generated or migrated for itself:

  • An automatically generated SESSION_SECRET, if you never set one;
  • Settings migrated from a legacy config.yml (see above);
  • SMTP settings migrated from an even older version, where they used to be stored in the database and configured from the admin panel (see configuring SMTP).

It's loaded with the lowest priority, so a real environment variable or a value in .env always overrides it.