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.
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.
masks.yml
are only applied on initial setup. They will not override any changes made
after installation.
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 |
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 |
masks.yml
or with the
MASKS_URL
var, then re-deploy. Cookies and devices will be
lost if the domain changes.
The following database adapters are supported:
db.adapter=postgresql
db.adapter=sqlite3
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 |
The first time masks boots it will populate the database with default data, including:
seeds
/MASKS_SEEDS
directoryENV
and masks.yml
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.
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 |
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
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.
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
.
There are several integrations with other services that expand Masks’
functionality. All settings for them are housed under the integration
key in
masks.yml
.
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 |
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 |