Configuration

how to configure masks...

Although masks will boot without any configuration, you will likely need to make some changes to suit your specific setup. Configuration can be supplied using ENV variables and/or a masks.yml file.

masks.yml

All of the settings outlined below can be overridden in your masks.yml. You can view all of the defaults in the masks source code.

Note: Most settings in your masks.yml are only applied on initial setup. They will not override any changes made after installation.

Environment variables

There are a few settings that are only controlled with environment variables:

name description default
MASKS_YML path to masks.yml /masks/masks.yml
MASKS_PORT port for the web server 1111
MASKS_THREADS number of threads per process 5

Minimal settings

At minimum, provide the name and public URL of your installation, along with any settings required to access dependencies like the database and redis.

name ENV var default
url MASKS_URL https://localhost:1111
name MASKS_NAME masks
timezone MASKS_TZ America/New_York
region MASKS_REGION US
Note To change your installation url after initial setup, change it in your masks.yml or with the MASKS_URL var, then re-deploy. Cookies and devices will be lost if the domain changes.

Database

The following database adapters are supported:

A redis is recommended, especially if you’re not using PostgreSQL. It will be used for caching and background work.

name ENV var default
redis.url REDIS_URL  
db.url DATABASE_URL  
db.adapter MASKS_DB_ADAPTER sqlite3 unless specified via the url
db.name MASKS_DB_NAME masks_production or data/production.sqlite3

Default data

The first time masks boots it will populate the database with default data, including:

name ENV var default
seeds MASKS_SEEDS  
manager.nickname MASKS_MANAGER_NICKNAME manager
manager.password MASKS_MANAGER_PASSWORD  
manager.email MASKS_MANAGER_EMAIL  
manager.nickname MASKS_MANAGER_NICKNAME  
manager.password MASKS_MANAGER_PASSWORD  

You can disable this behaviour with the SKIP_MIGRATIONS environment variable.

Advanced settings

Feature toggles

You can customize some of the features available to end-users depending on your use-case:

name default
nicknames.enabled true
emails.enabled true
emails.max_for_login 5
passwords.min_chars 8
passwords.max_chars 100
passkeys.enabled true
login_links.enabled true
totp_codes.enabled true
sms_codes.enabled true
webauthn.enabled true
webauthn.rp_name name or MASKS_NAME
backup_codes.min_chars 8
backup_codes.max_chars 100
backup_codes.total 10

Encryption

A private_key—stored on the filesystem—is used to encrypt and hash data stored in masks. Additional keys are derived from the private key if they are not supplied.

name ENV var default
private_key MASKS_PRIVATE_KEY ./data/private.key
secret_key MASKS_SECRET_KEY derived from private key
encryption_key MASKS_ENCRYPTION_KEY derived from private key
deterministic_key MASKS_DETERMINISTIC_KEY derived from private key
salt MASKS_SALT derived from private key

A private key will be created and saved automatically on first boot. If you’re using docker compose, make sure to store it on a local volume (along with other masks data). For example:

# docker-compose.yml
services:
  masks:
    ...
    volumes:
      - /example/masks/data:/masks/data

Theming

Masks can be customized with your organization’s name, branding, and more.

name ENV var default
theme.url    
theme.name MASKS_NAME masks
theme.light_logo_url    
theme.dark_logo_url    
theme.favicon_url    

Take a look at client configuration to customize the look and feel of client interactions.

Clients

Take a look at the guide to clients for information on the default settings for clients. Like most configuration, you can set them in your masks.yml.

Integrations

There are several integrations with other services that expand Masks’ functionality. All settings for them are housed under the integration key in masks.yml.

Asset storage

Logos, avatars, and other uploads are stored on the local filesystem by default. You can change the location or configure masks to store assets with a cloud provider.

name ENV var default
integration.storage MASKS_STORAGE_INTEGRATION disk
integration.s3.access_key_id MASKS_S3_ACCESS_KEY_ID  
integration.s3.secret_access_key MASKS_S3_SECRET_ACCESS_KEY  
integration.s3.region MASKS_S3_REGION  
integration.s3.bucket MASKS_S3_BUCKET  
integration.gcs.project MASKS_GCS_PROJECT  
integration.gcs.credentials MASKS_GCS_CREDENTIALS  
integration.gcs.bucket MASKS_GCS_BUCKET  
integration.azure_storage.storage_account_name MASKS_AZURE_STORAGE_ACCOUNT_NAME  
integration.azure_storage.storage_access_key MASKS_AZURE_STORAGE_ACCESS_KEY  
integration.azure_storage.container MASKS_AZURE_STORAGE_CONTAINER  

Email and phone

While masks can be used without sending email or SMS, it’s recommended to configure support for it. SMS & email verification, login links, and some notifications depend on it.

name ENV var default
integration.email MASKS_EMAIL_INTEGRATION smtp
integration.phone MASKS_PHONE_INTEGRATION twilio
integration.smtp.address MASKS_SMTP_ADDRESS  
integration.smtp.port MASKS_SMTP_PORT  
integration.smtp.domain MASKS_SMTP_DOMAIN  
integration.smtp.user_name MASKS_SMTP_USER_NAME  
integration.smtp.password MASKS_SMTP_PASSWORD  
integration.smtp.authentication MASKS_SMTP_AUTHENTICATION  
integration.twilio.account_sid MASKS_TWILIO_ACCOUNT_SID  
integration.twilio.auth_token MASKS_TWILIO_AUTH_TOKEN  
integration.twilio.service_sid MASKS_TWILIO_SERVICE_SID