Configuring Saveroom¶
Any questions, problems or suggestions with this guide? Ask a question in our issue tracker or contribute the change yourself at https://github.com/carneirofc/baserow/tree/develop/docs .
The table below shows all available environment variables supported by Saveroom. Some environment variables have different defaults, are not supported, are optional etc depending on how you installed Saveroom. See the specific installation guides for how to set these environment variables.
Not everything is configured this way. A handful of settings live in the database instead and are changed at runtime from the admin area — see Instance settings at the bottom of this page.
Environment Variables¶
The installation methods referred to in the variable descriptions are:
- The Standalone service images
- The ghcr.io/carneirofc/baserow "all in one" image
- The Docker compose install
Variables marked with Internal should only be changed if you know what you are doing.
Access Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_PUBLIC_URL | The public URL or IP that will be used to access the Saveroom tool. Always should start with http:// https:// even if accessing via an IP address. If you are accessing Saveroom over a non-standard (80) http port then make sure you append :YOUR_PORT to this variable. Setting this will override PUBLIC_BACKEND_URL and PUBLIC_WEB_FRONTEND_URL with BASEROW_PUBLIC_URL’s value. Set to empty to disable default of http://localhost in the compose to instead set PUBLIC_X_URLs. Note that other URL will be treated as a published application builder domains. |
http://localhost |
| BASEROW_EXTRA_PUBLIC_URLS | An optional comma-separated list of additional public URLs where Saveroom tool will be accessible. These URLs will have the same behavior as BASEROW_PUBLIC_URL (not treated as published applications). The difference is that BASEROW\_PUBLIC\_URL is used in email communication. This is useful when running Saveroom behind multiple domain names or when using different URLs for different network access (e.g., both public and private). Example: http://app.example.com,https://baserow.company.local. |
|
| BASEROW_CADDY_ADDRESSES | Not supported by standalone images. A comma separated list of supported Caddy addresses( https://caddyserver.com/docs/caddyfile/concepts#addresses). If a https:// url is provided the Caddy reverse proxy will attempt to automatically setup HTTPS with lets encrypt for you. If you wish your Saveroom to still be accessible on localhost and you set this value away from the default of :80 ensure you append “,http://localhost” | :80 |
| PUBLIC_BACKEND_URL | Please use BASEROW_PUBLIC_URL unless you are using the standalone ghcr.io/carneirofc/baserow/backend or ghcr.io/carneirofc/baserow/web-frontend images. The publicly accessible URL of the backend. Should include the port if non-standard. Ensure BASEROW_PUBLIC_URL is set to an empty value to use this variable in the compose setup. | $BASEROW_PUBLIC_URL, http://localhost:8000/ in the standalone images. |
| PUBLIC_WEB_FRONTEND_URL | Please use BASEROW_PUBLIC_URL unless you are using the standalone ghcr.io/carneirofc/baserow/backend or ghcr.io/carneirofc/baserow/web-frontend images. The publicly accessible URL of the web-frontend. Should include the port if non-standard. Ensure BASEROW_PUBLIC_URL is set to an empty value to use this variable in the compose setup. | $BASEROW_PUBLIC_URL, http://localhost:3000/ in the standalone images. |
| BASEROW_EMBEDDED_SHARE_URL | Optional URL for public sharing and email links that can be used if Saveroom is used inside an iframe on a different URL. | $PUBLIC_WEB_FRONTEND_URL |
| WEB_FRONTEND_PORT | The HTTP port that is being used to access Saveroom using. Only used by the docker-compose files. | Only used by the docker-compose.yml files, defaults to 80 but prior to 1.9 defaulted to 3000. |
| BASEROW_EXTRA_ALLOWED_HOSTS | An optional comma separated list of hostnames which will be added to the Saveroom's Django backend ALLOWED_HOSTS setting. In most situations you will not need to set this as the hostnames from BASEROW_PUBLIC_URL or PUBLIC_BACKEND_URL will be added to the ALLOWED_HOSTS automatically. This is only needed if you need to allow additional different hosts to be able to access your Saveroom. | |
| PRIVATE_BACKEND_URL | Only change this with standalone images. This is the URL used when the web-frontend server directly queries the backend itself when doing server side rendering. As such not only the browser, but also the web-frontend server should be able to make HTTP requests to the backend. The web-frontend nuxt server might not have access to the `PUBLIC_BACKEND_URL` or there could be a more direct route, (e.g. from container to container instead of via the internet). For example if the web-frontend and backend were containers on the same docker network this could be set to http://backend:8000. |
|
| BASEROW_CADDY_GLOBAL_CONF | Not supported by standalone images. Will be substituted into the Caddyfiles global config section. Set to “debug” to enable Caddies debug logging. | |
| BASEROW_MAX_IMPORT_FILE_SIZE_MB | The maximum file size in mb you can import to create a new table. Default 512Mb. | 512 |
Backend Configuration¶
| Name | Description | Defaults |
|---|---|---|
| SECRET_KEY | The Secret key used by Django for cryptographic signing such as generating secure password reset links and managing sessions. See https://docs.djangoproject.com/en/3.2/ref/settings/#std:setting-SECRET_KEY for more details | Required to be set by you in the docker-compose and standalone installs. Automatically generated by the ghcr.io/carneirofc/baserow image if not provided and stored in /baserow/data/.secret. |
| SECRET_KEY_FILE | Only supported by the ghcr.io/carneirofc/baserow image If set Saveroom will attempt to read the above SECRET_KEY from this file location instead. |
|
| BASEROW_JWT_SIGNING_KEY | The signing key that is used to sign the content of generated tokens. For HMAC signing, this should be a random string with at least as many bits of data as is required by the signing protocol. See https://django-rest-framework-simplejwt.readthedocs.io/en/latest/settings.html#signing-key for more details | Recommended to be set by you in the docker-compose and standalone installs (default to the SECRET_KEY). Automatically generated by the ghcr.io/carneirofc/baserow image if not provided and stored in /baserow/data/.jwt_signing_key. |
| BASEROW_ACCESS_TOKEN_LIFETIME_MINUTES | The number of minutes which specifies how long access tokens are valid. This will be converted in a timedelta value and added to the current UTC time during token generation to obtain the token’s default “exp” claim value. | 10 minutes. |
| BASEROW_REFRESH_TOKEN_LIFETIME_HOURS | The number of hours which specifies how long refresh tokens are valid. This will be converted in a timedelta value and added to the current UTC time during token generation to obtain the token’s default “exp” claim value. | 168 hours (7 days). |
| BASEROW_CACHE_TTL_SECONDS | How long (in seconds) to cache lookups of authenticated users, database tokens, instance-wide settings, and active licenses in Redis, to speed up requests and reduce database load. Set to 0 to disable these caches entirely. | 120 |
| BASEROW_BACKEND_LOG_LEVEL | The default log level used by the backend, supports ERROR, WARNING, INFO, DEBUG, TRACE | INFO |
| BASEROW_BACKEND_DATABASE_LOG_LEVEL | The default log level used for database related logs in the backend. Supports the same values as the normal log level. If you also enable BASEROW_BACKEND_DEBUG and set this to DEBUG you will be able to see all SQL queries in the backend logs. | ERROR |
| BASEROW_DJANGO_REQUEST_LOG_LEVEL | The log level for the django.request logger. Default is ERROR to suppress noisy 429 responses under heavy throttling. Supports ERROR, WARNING, INFO, DEBUG. |
ERROR |
| BASEROW_BACKEND_DEBUG | If set to “on” then will enable the non production safe debug mode for the Saveroom django backend. Only use this if you're using Saveroom in development mode. Note that this causes any installed licenses to deactivate and prevent you from adding a new license. | off |
| BASEROW_AMOUNT_OF_GUNICORN_WORKERS | The number of concurrent worker processes used by the Saveroom backend gunicorn server to process incoming requests | |
| BASEROW_AIRTABLE_IMPORT_SOFT_TIME_LIMIT | The maximum amount of seconds an Airtable migration import job can run. | 1800 seconds - 30 minutes |
| INITIAL_TABLE_DATA_LIMIT | The amount of rows that can be imported when creating a table. Defaults to empty which means unlimited rows. | |
| BASEROW_ROW_PAGE_SIZE_LIMIT | The maximum number of rows that can be requested at once. | 200 |
| BASEROW_MAX_FIELD_TEXT_LENGTH | The maximum number of characters accepted when writing a text based field value (single line text, long text, URL, and AI fields with a text output) via the API or web frontend. Existing longer values remain readable. | 1000000 |
| BASEROW_FORMULA_RANGE_MAX_ITEMS | The maximum number of items the range runtime formula function can generate. Prevents a small formula from producing an unbounded array. |
10000 |
| BASEROW_INTEGRATION_LOCAL_BASEROW_BATCH_OPERATION_SIZE_LIMIT | Controls how many rows can be created, updated, or deleted at once using Local Saveroom batch workflow actions. | 1000 |
| BASEROW_FILE_UPLOAD_SIZE_LIMIT_MB | The max file size in MB allowed to be uploaded by users into a Saveroom File Field. | 1048576 (1 TB or 1024*1024) |
| BASEROW_FILE_UPLOAD_ACTIVE_CONTENT_POLICY | Controls how uploads with active-content extensions (.html, .htm, .xhtml, .xml, .svg, .svgz) or MIME types (text/html, text/xml, application/xml, application/xhtml+xml, image/svg+xml) are handled. Set to download to allow them but store them as application/octet-stream without image previews. Set to block to reject them. |
download |
| BATCH_ROWS_SIZE_LIMIT | Controls how many rows can be created, deleted or updated at once using the batch endpoints. | 200 |
| BATCH_ROWS_SIZE_LIMIT | Controls how many rows can be created, deleted or updated at once using the batch endpoints. | 200 |
| FIELD_RULE_ROWS_LIMIT | Used in field rule operations to distinguish between small tables, where per-row results can be emitted, or big tables, where a full table update should be emitted. | 200 (if not provided, BATCH_ROWS_SIZE_LIMIT value will be used) |
| BASEROW_MAX_SNAPSHOTS_PER_GROUP | Controls how many application snapshots can be created per group. | -1 (unlimited) |
| BASEROW_SNAPSHOT_EXPIRATION_TIME_DAYS | Controls when snapshots expire, set in number of days. Expired snapshots will be automatically deleted. | 360 |
| BASEROW_CELERY_SEARCH_UPDATE_HARD_TIME_LIMIT | How long the Postgres full-text search Celery tasks can run for being killed. | 1800 |
| BASEROW_USE_PG_FULLTEXT_SEARCH | By default, Saveroom will use Postgres full-text as its search backend. If the product is installed on a system with limited disk space, and less accurate results / degraded search performance is acceptable, then switch this setting off by setting it to false. | true |
| BASEROW_PG_FULLTEXT_SEARCH_UPDATE_DATA_THROTTLE_SECONDS | The delay before triggering the task that updates full-text search data. A higher value reduces how often the task runs when many changes occur but delays how soon newly modified values become searchable. Only one update task will run per table. The value is in seconds | 2 (seconds) |
| BASEROW_ASGI_HTTP_MAX_CONCURRENCY | Specifies a limit for concurrent requests handled by a single gunicorn worker. The default is: no limit. | |
| BASEROW_IMPORT_EXPORT_RESOURCE_REMOVAL_AFTER_DAYS | Specifies the number of days after which an import/export resource will be automatically deleted. | 5 (days) |
Rate Limiting¶
Saveroom can throttle the number of concurrent requests a single user (or, optionally, a single anonymous IP) is allowed to have in flight at the same time. When enabled, excess requests are rejected immediately with a 429 Too Many Requests response — they do not wait for a slot to free up. Repeat offenders can additionally be added to a short-lived blacklist that is consulted by a lightweight middleware before authentication runs, so that further requests are rejected with zero DB / DRF overhead.
| Name | Description | Defaults |
|---|---|---|
| BASEROW_MAX_CONCURRENT_USER_REQUESTS | Limits the number of concurrent requests per authenticated user. When set to a value greater than 0, enables the concurrent-request throttle. Set to -1 or leave unset to disable throttling. Can be overridden on a per-user basis by setting the concurrency_limit field on the user's profile, which takes precedence over this value when greater than 0. |
-1 (disabled) |
| BASEROW_CONCURRENT_USER_REQUESTS_THROTTLE_TIMEOUT | How long (in seconds) an in-flight request stays counted toward the concurrent-request throttle before it is treated as stale and evicted automatically. | 180 |
| BASEROW_THROTTLE_BLACKLIST_TTL_SECONDS | Cooldown (in seconds) applied to denied requests. When greater than 0, a denied request blacklists the token (or IP, if enabled) for that many seconds; subsequent requests are rejected by the throttle-blacklist middleware with zero DB/DRF overhead, matching DRF's standard Throttled response shape (with Retry-After). When set to 0 or a negative value (default), no blacklist is kept and no Retry-After is emitted. Only takes effect when BASEROW_MAX_CONCURRENT_USER_REQUESTS is enabled. |
-1 (disabled) |
| BASEROW_THROTTLE_IP_ENABLED | When "true", anonymous requests are included in the concurrent-request throttle using the client IP as the key. Without this flag, anonymous requests bypass the throttle entirely. Independent of the blacklist: when the blacklist is also enabled (BASEROW_THROTTLE_BLACKLIST_TTL_SECONDS > 0) the IP-blacklist middleware will additionally reject repeat-offender IPs before they reach the rest of the stack. Only takes effect when BASEROW_MAX_CONCURRENT_USER_REQUESTS is enabled. |
false |
Backend Database Configuration¶
| Name | Description | Defaults |
|---|---|---|
| DATABASE_HOST | The hostname of the postgres database Saveroom will use to store its data in. | Defaults to db in the standalone and compose installs. If not provided in the `ghcr.io/carneirofc/baserow` install then the embedded Postgres will be setup and used. |
| DATABASE_USER | The username of the database user Saveroom will use to connect to the database at DATABASE_HOST | baserow |
| DATABASE_PORT | The port Saveroom will use when trying to connect to the postgres database at DATABASE_HOST | 5432 |
| DATABASE_NAME | The database name Saveroom will use to store data in. | baserow |
| DATABASE_PASSWORD | The password of DATABASE_USER on the postgres server at DATABASE_HOST | Required to be set by you in the docker-compose and standalone installs. Automatically generated by the ghcr.io/carneirofc/baserow image if not provided and stored in /baserow/data/.pgpass. |
| DATABASE_PASSWORD_FILE | Only supported by the ghcr.io/carneirofc/baserow image If set Saveroom will attempt to read the above DATABASE_PASSWORD from this file location instead. |
|
| DATABASE_OPTIONS | Optional extra options as a JSON formatted string to use when connecting to the database, see this documentation for more details. | |
| DATABASE_URL | Alternatively to setting the individual DATABASE_ parameters above instead you can provide one standard postgres connection string in the format of: postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&…]. Please note this will completely override all other DATABASE_* settings and ignore them. | |
| DATABASE_READ_{n}_HOST | Optionally provide database information of read-only replicas. Format is the same as the normal database configuration. Replace {n} with 1, 2, 3, etc for every read-only replica that is available. | 5432 |
| DATABASE_READ_{n}_USER | 5432 | |
| DATABASE_READ_{n}_PORT | 5432 | |
| DATABASE_READ_{n}_NAME | baserow | |
| DATABASE_READ_{n}_PASSWORD | ||
| DATABASE_READ_{n}_OPTIONS | ||
| DATABASE_READ_{n}_URL | ||
| MIGRATE_ON_STARTUP | If set to “true” when the Saveroom backend service starts up it will automatically apply database migrations. Set to any other value to disable. If you disable this then you must remember to manually apply the database migrations when upgrading Saveroom to a new version. | true |
| BASEROW_TRIGGER_SYNC_TEMPLATES_AFTER_MIGRATION | If set to “true” when after a migration Saveroom will automatically sync all builtin Saveroom templates in the background. If you are using a postgres database which is constrained to fewer than 10000 rows then we recommend you disable this as the Saveroom templates will go over that row limit. To disable this set to any other value than “true” | true |
| BASEROW_SYNC_TEMPLATES_TIME_LIMIT | The number of seconds before the background sync templates job will timeout if not yet completed. | 1800 |
| SYNC_TEMPLATES_ON_STARTUP | Deprecated please use BASEROW_TRIGGER_SYNC_TEMPLATES_AFTER_MIGRATION If provided has the same effect of BASEROW_TRIGGER_SYNC_TEMPLATES_AFTER_MIGRATION for backwards compatibility reasons. If BASEROW_TRIGGER_SYNC_TEMPLATES_AFTER_MIGRATION is set it will override this value. | true |
| DONT_UPDATE_FORMULAS_AFTER_MIGRATION | Saveroom’s formulas have an internal version number. When upgrading Saveroom if the formula language has also changed then after the database migration has run Saveroom will also automatically recalculate all formulas if they have a different version. Set this to any non empty value to disable this automatic update if you would prefer to run the update_formulas management command manually yourself. Formulas might break if you forget to do so after an upgrade of Saveroom until and so it is recommended to leave this empty. | |
| POSTGRES_STARTUP_CHECK_ATTEMPTS | When Saveroom's Backend service starts up it first checks to see if the postgres database is available. It checks 5 times by default, after which if it still has not connected it will crash. | 5 |
| BASEROW_PREVENT_POSTGRESQL_DATA_SYNC_CONNECTION_TO_DATABASE | If true, then it's impossible to connect to the Saveroom PostgreSQL database using the PostgreSQL data sync. | true |
| BASEROW_POSTGRESQL_DATA_SYNC_BLACKLIST | Optionally provide a comma separated list of hostnames that the Saveroom PostgreSQL data sync can't connect to. (e.g. "localhost,db.internal") | |
| BASEROW_POSTGRESQL_DATA_SYNC_STATEMENT_TIMEOUT | The maximum time in seconds that a single SQL statement is allowed to run during a PostgreSQL data sync before it is cancelled. Increase this value for larger installations with slow queries. | 180 |
| BASEROW_CONN_MAX_AGE | How long (in seconds) a database connection may be reused. Set to 0 to close connections after each request. With WSGI, values > 0 can improve performance. With ASGI, use caution as persistent connections can multiply across async coroutines. Applied to all configured databases (primary and read replicas). | 0 |
Redis Configuration¶
| Name | Description | Defaults |
|---|---|---|
| REDIS_HOST | The hostname of the redis database Saveroom will use for caching and real time collaboration. | Defaults to redis in the standalone and compose installs. If not provided in the `ghcr.io/carneirofc/baserow` install then the embedded Redis will be setup and used. |
| REDIS_PORT | The port Saveroom will use when trying to connect to the redis database at REDIS_HOST | 6379 |
| REDIS_USER | The username of the redis user Saveroom will use to connect to the redis at REDIS_HOST | |
| REDIS_PASSWORD | The password of REDIS_USER on the redis server at REDIS_HOST | Required to be set by you in the docker-compose and standalone installs. Automatically generated by the ghcr.io/carneirofc/baserow image if not provided and stored in /baserow/data/.redispass. |
| REDIS_PASSWORD_FILE | Only supported by the ghcr.io/carneirofc/baserow image If set Saveroom will attempt to read the above REDIS_PASSWORD from this file location instead. |
|
| REDIS_PROTOCOL | The redis protocol used when connecting to the redis at REDIS_HOST Can either be ‘redis’ or ‘rediss’. | redis |
| REDIS_SSL_CERT_REQS | When REDIS_PROTOCOL is rediss, whether the server certificate is verified: required, optional or none. |
required |
| REDIS_SSL_CA_CERTS | When REDIS_PROTOCOL is rediss, path to the CA bundle used to verify the server certificate. |
|
| REDIS_URL | Alternatively to setting the individual REDIS_ parameters above instead you can provide one standard redis connection string in the format of: redis://:[password]@[redishost]:[redisport] |
Celery Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_CELERY_BEAT_STARTUP_DELAY | The number of seconds the celery beat worker sleeps before starting up. | 15 |
| BASEROW_CELERY_BEAT_DEBUG_LEVEL | The logging level for the celery beat service. | INFO |
| BASEROW_AMOUNT_OF_WORKERS | The number of concurrent celery worker processes used to process asynchronous tasks. If not set will default to the number of available cores. Each celery process uses memory, to reduce Saveroom's memory footprint consider setting and reducing this variable. | 1 for the All-in-one image. Defaults to empty and hence the number of available cores in the standalone images. |
| BASEROW_RUN_MINIMAL | When BASEROW_AMOUNT_OF_WORKERS is 1 and this is set to a non empty value Saveroom will not run the export-worker but instead run both the celery export and normal tasks on the normal celery worker. Set this to lower the memory usage of Saveroom in expense of performance. | |
| BASEROW_MAX_HEALTHY_CELERY_QUEUE_SIZE | Used as maximum values in the /api/_health/celery-queue/?queue=celery&queue=export endpoint. If the number of tasks in the queue exceeds this value, then the health check fails. |
10 |
Webhook Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_WEBHOOKS_ALLOW_PRIVATE_ADDRESS | If set to any non empty value allows webhooks to access all addresses. Enabling this flag is a security risk as it will allow users to send webhook requests to internal addresses on your network. Instead consider using the three variables below first to allow access to only some internal network hostnames or IPs. | |
| BASEROW_WEBHOOKS_URL_REGEX_BLACKLIST | Disabled if BASEROW_WEBHOOKS_ALLOW_PRIVATE_ADDRESS is set. List of comma seperated regexes used to validate user configured webhook URLs, will show the user an error if any regexes match their webhook URL and prevent it from running. Applied before and so supersedes BASEROW_WEBHOOKS_IP_WHITELIST and BASEROW_WEBHOOKS_IP_BLACKLIST. Do not include any schema like http://, https:// as regexes will only be run against the hostname/IP of the user configured URL. For example set this to ^(?!(www\.)?allowedhost\.com).* to block all hostnames and IPs other than allowedhost.com or www.allowedhost.com. |
|
| BASEROW_WEBHOOKS_IP_WHITELIST | Disabled if BASEROW_WEBHOOKS_ALLOW_PRIVATE_ADDRESS is set. List of comma seperated IP addresses or ranges that webhooks will be allowed to use after the webhook URL has been resolved to an IP using DNS. Only checked if the URL passes the BASEROW_WEBHOOKS_URL_REGEX_BLACKLIST. Takes precedence over BASEROW_WEBHOOKS_IP_BLACKLIST meaning that a whitelisted IP will always be let through regardless of the ranges in BASEROW_WEBHOOKS_IP_BLACKLIST. So use BASEROW_WEBHOOKS_IP_WHITELIST to punch holes the ranges in BASEROW_WEBHOOKS_IP_BLACKLIST, and not the other way around. Accepts a string in the format: "127.0.0.1/32,192.168.1.1/32" | |
| BASEROW_WEBHOOKS_IP_BLACKLIST | Disabled if BASEROW_WEBHOOKS_ALLOW_PRIVATE_ADDRESS is set. List of comma seperated IP addresses or ranges that webhooks will be denied from using after the URL has been resolved to an IP using DNS. Only checked if the URL passes the BASEROW_WEBHOOKS_URL_REGEX_BLACKLIST. BASEROW_WEBHOOKS_IP_WHITELIST supersedes any ranges specified in this variable. Accepts a string in the format: "127.0.0.1/32,192.168.1.1/32" | |
| BASEROW_WEBHOOKS_URL_CHECK_TIMEOUT_SECS | Disabled if BASEROW_WEBHOOKS_ALLOW_PRIVATE_ADDRESS is set. How long to wait before timing out and returning an error when checking if an url can be accessed for a webhook. | 10 seconds |
| BASEROW_DATA_SYNC_ALLOW_PRIVATE_ADDRESS | If set to false, data syncs that fetch from a user configured URL (such as an iCal feed) are blocked from reaching private/internal network addresses and ports other than 80, 443, 8000, 8080 and 8443 (SSRF protection). Defaults to true for backwards compatibility; setting it to false is recommended when your data sources are hosted on public addresses and standard ports. |
true |
| BASEROW_WEBHOOKS_MAX_CONSECUTIVE_TRIGGER_FAILURES | The number of consecutive trigger failures that can occur before a webhook is disabled. | 8 |
| BASEROW_WEBHOOKS_MAX_RETRIES_PER_CALL | The max number of retries per webhook call. | 8 |
| BASEROW_WEBHOOKS_MAX_PER_TABLE | The max number of webhooks per Saveroom table. | 20 |
| BASEROW_WEBHOOKS_MAX_CALL_LOG_ENTRIES | The maximum number of call log entries stored per webhook. | 10 |
| BASEROW_WEBHOOKS_REQUEST_TIMEOUT_SECONDS | How long to wait on making the webhook request before timing out. | 5 |
| BASEROW_MAX_WEBHOOK_CALLS_IN_QUEUE_PER_WEBHOOK | Maximum number of calls that can be in the webhook's queue. Can be useful to limit when massive numbers of webhooks are triggered due an automation loop. If not set or set to 0, then there is no limit. |
0 |
| BASEROW_WEBHOOKS_BATCH_LIMIT | This limit applies to all webhook_event_types that split large payloads into multiple batches. Each batch is a separate request with the same event_id and an incremental batch_id. This parameter sets the maximum number of batches per event. Set to 0 for unlimited batches. | 5 |
| BASEROW_WEBHOOK_ROWS_ENTER_VIEW_BATCH_SIZE | Defines the number of rows that can be sent in a single webhook call of type view.rows_entered. This is used to prevent the webhook call from being too large and potentially causing issues while serializing the data or sending it over the network to the webhook endpoint. |
200 |
Backend Misc Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_ENABLE_SECURE_PROXY_SSL_HEADER | Set to any non-empty value to ensure Saveroom generates https:// next links provided by paginated API endpoints. Saveroom will still work correctly if not enabled, this is purely for giving the correct https url for clients of the API. If you have setup Saveroom to use Caddy's auto HTTPS or you have put Saveroom behind a reverse proxy which: Handles HTTPS Strips the X-Forwarded-Proto header from all incoming requests. * Sets the X-Forwarded-Proto header and sends it to Saveroom. Then you can safely set BASEROW_ENABLE_SECURE_PROXY_SSL_HEADER=yes to ensure Saveroom generates https links for pagination correctly. |
|
| ADDITIONAL_APPS | A comma separated list of additional django applications to add to the INSTALLED_APPS django setting | |
| BASEROW_MAX_REQUEST_BODY_SIZE_MB | The largest request body, in MB, the backend accepts (Django's DATA_UPLOAD_MAX_MEMORY_SIZE). JSON payloads count too, including table imports, which send the parsed file as JSON, so keep it well above BASEROW_MAX_IMPORT_FILE_SIZE_MB. Bodies are read into memory, so this also bounds per-request memory use. |
1024 |
| HOURS_UNTIL_TRASH_PERMANENTLY_DELETED | Items from the trash will be permanently deleted after this number of hours. | |
| DISABLE_ANONYMOUS_PUBLIC_VIEW_WS_CONNECTIONS | When sharing views publicly a websocket connection is opened to provide realtime updates to viewers of the public link. To disable this set any non empty value. When disabled publicly shared links will need to be refreshed to see any updates to the view. | |
| BASEROW_PRESENCE_VISIBLE_USERS | Controls realtime user presence in the grid header. The value sets how many user badges are shown before an overflow counter appears; set to 0 to disable presence entirely (no data is tracked or broadcast). Should be set on both the backend and web-frontend services. | 3 |
| BASEROW_WAIT_INSTEAD_OF_409_CONFLICT_ERROR | When updating or creating various resources in Saveroom if another concurrent operation is ongoing (like a snapshot, duplication, import etc) which would be affected by your modification a 409 HTTP error will be returned. If you instead would prefer Saveroom to not return a 409 and just block waiting until the operation finishes and then to perform the requested operation set this flag to any non-empty value. | |
| BASEROW_JOB_CLEANUP_INTERVAL_MINUTES | How often the job cleanup task will run. | 5 |
| BASEROW_JOB_EXPIRATION_TIME_LIMIT | How long before a Saveroom job will be kept before being cleaned up. | 30 * 24 * 60 (24 days) |
| BASEROW_JOB_SOFT_TIME_LIMIT | The number of seconds a Saveroom job can run before being terminated. | 1800 |
| MINUTES_UNTIL_ACTION_CLEANED_UP | How long before actions are cleaned up, actions are used to let you undo/redo so this is effectively the max length of time you can undo/redo can action. | 120 |
| BASEROW_DISABLE_MODEL_CACHE | When set to any non empty value the model cache used to speed up Saveroom will be disabled. Useful to enable when debugging Saveroom errors if they are possibly caused by the model cache itself. | |
| DJANGO_SETTINGS_MODULE | INTERNAL The settings python module to load when starting up the Backend django server. You shouldn’t need to set this yourself unless you are customizing the settings manually. | |
| BASEROW_BACKEND_BIND_ADDRESS | INTERNAL The address that Saveroom’s backend service will bind to. | |
| BASEROW_BACKEND_PORT | INTERNAL Controls which port the Saveroom backend service binds to. | |
| BASEROW_WEBFRONTEND_BIND_ADDRESS | INTERNAL The address that Saveroom’s web-frontend service will bind to. | |
| BASEROW_INITIAL_CREATE_SYNC_TABLE_DATA_LIMIT | The maximum number of rows you can import in a synchronous way | 5000 |
| BASEROW_MAX_ROW_REPORT_ERROR_COUNT | The maximum row error count tolerated before a file import fails. Before this max error count the import will continue and the non failing rows will be imported and after it, no rows are imported at all. | 30 |
| BASEROW_ROW_HISTORY_CLEANUP_INTERVAL_MINUTES | Sets the interval for periodic clean up check of the row edit history in minutes. | 30 |
| BASEROW_ROW_HISTORY_RETENTION_DAYS | The number of days that the row edit history will be kept. | 180 |
| BASEROW_ICAL_VIEW_MAX_EVENTS | The maximum number of events returned from ical feed endpoint. Empty value means no limit. | |
| BASEROW_DEADLOCK_INITIAL_BACKOFF | The initial backoff time for database deadlock retries. | 2 |
| BASEROW_DEADLOCK_MAX_RETRIES | The maximum number of database deadlock retries. | 1 |
| BASEROW_REALTIME_REPLAY_MAX_EVENTS | Maximum number of missed events replayed to a reconnecting WebSocket client. When the count exceeds this limit, the client is asked to refresh instead of receiving individual events. Set to 0 to disable event recording and replay. Full events are replayable for the configured retention window, independently of JWT lifetime. Expired events become routing summaries without business payloads; relevant missed expired history requires a refresh. Cleanup continues when recording is disabled. |
200 |
| BASEROW_REALTIME_REPLAY_RETENTION_HOURS | Maximum age in hours of full realtime events available to replay after a WebSocket reconnect. Must be a positive integer. Increasing this window retains more full payloads and requires more database storage, but cannot restore events already compacted. Independent of JWT lifetime. | 24 |
| BASEROW_DEPENDANT_ROWS_REALTIME_UPDATE_LIMIT | Per table, the maximum number of rows changed by a dependency cascade (formulas, lookups, link row display values in other tables) that are broadcast as exact realtime row updates. Above the limit, subscribers of the affected table receive a whole-table refresh event instead. Set to 0 to disable realtime events for dependant rows entirely. Higher values increase the background serialization work and websocket traffic per edit. |
200 |
| BASEROW_PERIODIC_FIELD_UPDATE_BATCH_COUNT | The number of parallel tasks the periodic field update (e.g. now() formulas) is split into each cycle. Raise it to spread the work across more workers when a single task can't refresh every workspace before the next cycle starts. If cycles are still being skipped, also give each cycle more time with BASEROW_PERIODIC_FIELD_UPDATE_CRONTAB. |
1 |
Backup and contents API configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_BACKUP_SCHEDULE_TICK_CRONTAB | How often the periodic task checks for backup schedules that became due, as a crontab expression. Every minute by default so a schedule fires close to the moment its own cron expression asks for. Raise it to reduce scheduler wake-ups. | * * * * * |
| BASEROW_CONTENTS_API_MAX_ROWS | The maximum number of rows the /api/contents/ endpoints return in a single synchronous response. Larger requests are refused with ERROR_CONTENTS_TOO_LARGE and should use /api/backups/ instead. Set to 0 to disable the limit. |
100000 |
| BASEROW_DATA_DESTINATIONS | A JSON list declaring the external storage that backups and datalake table exports are written to. Credentials live only here, never in the database; schedules and the API reference a destination by name (a url-safe slug). Every entry has name, type (s3, azure or filesystem) and optionally prefix (the key prefix everything is written under), purposes (a subset of ["backup", "datalake"], both by default) and allow_trust_public_key (default false; lets a staff member trust the signing key of a backup made by another instance when restoring from this destination). s3 requires bucket and accepts region, endpoint_url (for MinIO, Ceph and other S3-compatible stores), addressing_style, signature_version, use_ssl, verify, access_key_id, secret_access_key and session_token; without static keys the standard AWS credential chain (IRSA, instance profile) is used. azure requires container and one of account_key, connection_string or sas_token, plus account_name unless a connection string is given; endpoint_suffix and custom_domain are optional. filesystem requires an absolute root, typically a mounted volume. Any secret can be given as <key>_file instead, a path whose content is read at startup (Docker/Kubernetes secret mounts). Unknown keys and malformed entries fail fast at startup. Example: [{"name": "lake", "type": "s3", "bucket": "baserow-lake", "endpoint_url": "http://minio:9000", "access_key_id_file": "/run/secrets/s3_key", "secret_access_key_file": "/run/secrets/s3_secret"}]. |
[] |
| BASEROW_TABLE_EXPORT_SCHEDULE_TICK_CRONTAB | How often the periodic task checks for datalake table export schedules that became due, as a crontab expression. | * * * * * |
| BASEROW_DATA_EXPORT_CHUNK_SIZE | How many rows a datalake table export reads at once. Each chunk becomes a Parquet row group, so this bounds the memory an export uses. | 5000 |
| BASEROW_DATA_EXPORT_MAX_ROWS_PER_FILE | The maximum number of rows in one Parquet part file of a table export; larger exports are split over several parts. | 1000000 |
| BASEROW_DATA_EXPORT_WATERMARK_OVERLAP_SECONDS | How far an incremental table export reaches back before the previous export, to catch rows that were committed with an older modification time while that export ran. Rows in the overlap are exported twice, the lake keeps the one with the highest updated_on. |
300 |
| BASEROW_DATA_EXPORT_TMP_DIR | The directory Parquet part files are written to before they are uploaded to the destination. Point it at a volume large enough for the biggest table. Empty uses the system temporary directory. | |
| BASEROW_DATA_EXPORT_SOFT_TIME_LIMIT | The time in seconds an export of all tables of one schedule may take before the worker stops it. | 21600 |
Data sync configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_TWO_WAY_SYNC_MAX_CONSECUTIVE_FAILURES | Indicates the maximum number of consecutive two-way data sync updates before deactivating the two-way sync. | 8 |
| BASEROW_TWO_WAY_SYNC_MAX_RETRIES | Indicates the maximum of or two-way data sync create, update, or delete row retries before considering it a failure. | 3 |
| BASEROW_DATA_SYNC_ALLOW_PRIVATE_ADDRESS | If set to false, data syncs that fetch from a user configured URL (such as an iCal feed) are blocked from reaching private/internal network addresses and ports other than 80, 443, 8000, 8080 and 8443 (SSRF protection). Defaults to true for backwards compatibility; setting it to false is recommended when your data sources are hosted on public addresses and standard ports. |
true |
Automation workflow configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_AUTOMATION_HISTORY_PAGE_SIZE_LIMIT | The maximum number of automation history entries returned per page. | 100 |
| BASEROW_AUTOMATION_WORKFLOW_RATE_LIMIT_MAX_RUNS | The maximum number of workflow runs that can be started within the rate limit window before new runs are blocked. | 10 |
| BASEROW_AUTOMATION_WORKFLOW_RATE_LIMITS | A comma-separated list of integer pairs formatted as max_runs,window_seconds. For example, 10,5,20,60 means 10 executions per 5 seconds and 20 executions per 60 seconds. |
"10,5,30,300,100,3600" |
| BASEROW_AUTOMATION_WORKFLOW_RATE_LIMIT_CACHE_EXPIRY_SECONDS | The number of seconds the workflow rate limit counters are retained in cache. | 5 |
| BASEROW_AUTOMATION_WORKFLOW_HISTORY_RATE_LIMIT_CACHE_EXPIRY_SECONDS | The number of seconds the workflow history rate limit counters are retained in cache. If unset, it uses the workflow rate limit cache expiry. | 5 |
| BASEROW_AUTOMATION_WORKFLOW_ERROR_LIMITS | A comma-separated list of integer pairs formatted as max_errors,window_seconds. For example, 5,30,10,300 means more than 5 errors in 30 seconds or more than 10 errors in 300 seconds disables the workflow. |
'20,300' |
| BASEROW_AUTOMATION_WORKFLOW_MAX_CONSECUTIVE_ERRORS | The maximum number of consecutive workflow errors allowed before the workflow is disabled. | 5 |
| BASEROW_AUTOMATION_WORKFLOW_TIMEOUT_HOURS | The number of hours after which a running workflow is considered timed out. | 24 |
| BASEROW_AUTOMATION_WORKFLOW_HISTORY_MAX_DAYS | The number of days automation workflow history entries are retained. | 30 |
| BASEROW_AUTOMATION_WORKFLOW_HISTORY_MAX_ENTRIES | The maximum number of workflow history entries retained per workflow. | 50 |
Backend Application Builder Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_BUILDER_DOMAINS | A comma separated list of domain names that can be used as the domains to create sub domains in the application builder. |
User file upload Configuration¶
Saveroom needs somewhere to store the following types of files: * Files uploaded by users in Saveroom Table's using the File Field type * User triggered exports of tables and views
Filesystem Default¶
By default, Saveroom will store these files on the file system at the location set by
the MEDIA_ROOT environment variable, which is /baserow/media in our ghcr.io/carneirofc/baserow/backend
image or $DATA_DIR/media for the ghcr.io/carneirofc/baserow all-in-one image.
Warning: If Saveroom is storing user files on the file system and MEDIA_ROOT is not part of a persistent volume, then all uploaded user files will be lost if you remove the container. Our default docker commands and docker compose files ensure this location will be mounted to a persistent docker volume for you if you are using them.
Serving User Files when stored on the file system¶
Any uploaded files need to be served back to the user when they visit Saveroom in the
browser. Our ghcr.io/carneirofc/baserow image and some of our docker-compose.yml templates
come with a Caddy reverse proxy which is configured to serve
back any user uploaded files which are stored in the data/media volume.
If you do not wish to use our default Caddy proxy, place your own reverse proxy in front
of the backend and web-frontend services and have it serve user files from the media
volume. Django itself only serves MEDIA_URL when DEBUG is on, so in production
something in front has to.
Exported files and backups are the exception: they are downloaded through the API,
streamed out of the storage by the backend, so they need no media route and work the
same whether the files sit on a volume or in a bucket the browser cannot reach. The
link is short lived and signed; BASEROW_EXPORT_DOWNLOAD_TOKEN_MAX_AGE_SECONDS
(default 600) controls how long, and BASEROW_EXPORT_DOWNLOAD_BLOCK_SIZE (default
65536) how much is read per chunk while streaming.
On OpenShift/Kubernetes the Helm chart routes by path and has no media route at all, so a deployment that relies on file fields needs object storage.
When the workers and the web process disagree about the storage¶
When exports are written by a Celery worker in one container and downloaded through a
web process in another, the two must share the storage. If they do not, the export
finishes perfectly and the download then fails — which is why the download reports a
misconfigured file storage rather than a missing file, and why a worker writes a probe
file that the web process reads back. The result is on the instance health page
(/api/_health/full/, Admin → Health), so the split is visible before anyone runs
an export. BASEROW_SHARED_STORAGE_PROBE_INTERVAL_MINUTES (default 5) controls how
often the probe is written; the check allows three intervals before it complains.
File Service alternatives¶
You can alternatively configure Saveroom to store files by uploading them to an external service. This is highly recommended if you wish to horizontally scale Saveroom or deploy it in a distributed manner.
We support the following types of file storage service. Follow each link to documentation showing all available UPPER_CASE settings that you can set as environment variables to set up the desired provider.
- AWS S3, or any S3 compatible service such as Backblaze or Digital Ocean spaces
- When using AWS S3 we recommend you set the
DOWNLOAD_FILE_VIA_XHR=1environment variable. - Google Cloud Storage
- Azure Cloud Storage
Our default docker compose files do not by default include all available user file environment
variables to reduce their size. When using these docker compose files make sure that any
AWS_, GS_ or AZURE_ env vars you wish to use have been added to the
x-backend-variables section.
CORS Issues¶
When using a 3rd party file storage service which is serving files from another domain than your Saveroom, you need to make sure CORS is configured correctly.
User File Variables Table¶
| Name | Description | Defaults |
|---|---|---|
| MEDIA_URL | The URL at which user uploaded media files will be made available. Set this to a different origin, for example https://media.baserow.example.com/media/, to serve user uploads from an isolated media domain. |
$PUBLIC_BACKEND_URL/media/ |
| MEDIA_ROOT | INTERNAL The folder in which the backend will store user uploaded files | /baserow/media or $DATA_DIR/media for the ghcr.io/carneirofc/baserow all-in-one image |
| AWS_ACCESS_KEY_ID | The access key for your AWS account. When set to anything other than empty will switch Saveroom to use a S3 compatible bucket for storing user file uploads. | |
| AWS_SECRET_ACCESS_KEY | The access secret key for your AWS account. | |
| AWS_SECRET_ACCESS_KEY_FILE_PATH | Optional The path to a file containing access secret key for your AWS account. | |
| AWS_STORAGE_BUCKET_NAME | Your Amazon Web Services storage bucket name. | |
| AWS_S3_REGION_NAME | Optional Name of the AWS S3 region to use (eg. eu-west-1) | |
| AWS_S3_ENDPOINT_URL | Optional Custom S3 URL to use when connecting to S3, including scheme. | |
| AWS_S3_CUSTOM_DOMAIN | Optional Your custom domain where the files can be downloaded from. | |
| AWS_* | Optional All other AWS_ prefixed settings mentioned here are also supported. | |
| GC_* | All GC_ prefixed settings mentioned here are also supported. | |
| GS_CREDENTIALS_FILE_PATH | Optional The path to a Google service account file for credentials. | |
| AZURE_* | All AZURE_ prefixed settings mentioned here are also supported. | |
| AZURE_ACCOUNT_KEY_FILE_PATH | Optional The path to a file containing your Azure account key. |
Email Configuration¶
| Name | Description | Defaults |
|---|---|---|
| FROM_EMAIL | The email address Saveroom will send emails from. | |
| BASEROW_BRANDING_APP_NAME | The product name used in emails and in the API docs title, Saveroom by default. The web-frontend reads the same variable for its runtime branding, see Branding. |
|
| EMAIL_SMTP | If set to any non empty value then Saveroom will start sending emails using the configuration options below. If not set then Saveroom will not send emails and just log them to the Celery worker logs instead. | |
| EMAIL_SMTP_USE_TLS | If set to any non empty value then Saveroom will attempt to send emails using TLS.Whether to use a TLS (secure) connection when talking to the SMTP server. This is used for explicit TLS connections, generally on port 587. If you are experiencing hanging connections, see the implicit TLS setting EMAIL_SMTP_USE_SSL. | |
| EMAIL_SMTP_USE_SSL | If set to any non empty value then an implicit TLS (secure) connection will be used when talking to the SMTP server. In most email documentation this type of TLS connection is referred to as SSL. It is generally used on port 465. If you are experiencing problems, see the explicit TLS setting EMAIL_SMTP_USE_TLS. Note that EMAIL_SMTP_USE_TLS/EMAIL_SMTP_USE_SSL are mutually exclusive, so only set one of those settings to True. | |
| EMAIL_SMTP_HOST | The host of the external SMTP server that Saveroom should use to send emails. | |
| EMAIL_SMTP_PORT | The port used to connect to $EMAIL_SMTP_HOST on. | |
| EMAIL_SMTP_USER | The username to authenticate with $EMAIL_SMTP_HOST when sending emails. | |
| EMAIL_SMTP_PASSWORD | The password to authenticate with $EMAIL_SMTP_HOST when sending emails. | |
| EMAIL_SMTP_SSL_CERTFILE_PATH | If EMAIL_SMTP_USE_SSL or EMAIL_SMTP_USE_TLS is set, you can optionally specify the path to a PEM-formatted certificate chain file to use for the SSL connection. If using docker then you will need to mount in this file into all the Saveroom backend containers. | |
| EMAIL_SMTP_SSL_KEYFILE_PATH | EMAIL_SMTP_USE_SSL or EMAIL_SMTP_USE_TLS is set, you can optionally specify the path to a PEM-formatted private key file to use for the SSL connection. If using docker then you will need to mount in this file into all the Saveroom backend containers. Note that setting EMAIL_SMTP_SSL_CERTFILE_PATH and EMAIL_SMTP_SSL_KEYFILE_PATH doesn’t result in any certificate checking. They’re passed to the underlying SSL connection. Please refer to the documentation of Python’s ssl.wrap_socket() function for details on how the certificate chain file and private key file are handled. |
Web-frontend Configuration¶
| Name | Description | Defaults |
|---|---|---|
| DOWNLOAD_FILE_VIA_XHR | Set to `1` to force download links to download files via XHR query to bypass `Content-Disposition: inline` that can't be overridden in another way. If your files are stored under another origin, you also must add CORS headers to your server. | 0 |
| BASEROW_DISABLE_PUBLIC_URL_CHECK | When opening the Saveroom login page a check is run to ensure the PUBLIC_BACKEND_URL/BASEROW_PUBLIC_URL variables are set correctly and your browser can correctly connect to the backend. If misconfigured an error is shown. If you wish to disable this check and warning set this to any non empty value. | |
| ADDITIONAL_MODULES | Internal A list of file paths to Nuxt module.js files to load as additional Nuxt modules into Saveroom on startup. | |
| BASEROW_DISABLE_GOOGLE_DOCS_FILE_PREVIEW | Set to `true` or `1` to disable Google docs file preview. | |
| BASEROW_MAX_SNAPSHOTS_PER_GROUP | Controls how many application snapshots can be created per workspace. | 50 |
| BASEROW_USE_PG_FULLTEXT_SEARCH | By default, Saveroom will use Postgres full-text as its search backend. If the product is installed on a system with limited disk space, and less accurate results / degraded search performance is acceptable, then switch this setting off by setting it to false. | true |
| BASEROW_UNIQUE_ROW_VALUES_SIZE_LIMIT | Sets the limit for the automatic detection of multiselect options when converting a text field to a multiselect field. Increase the value to detect more options automatically, but consider performance implications. | 100 |
| BASEROW_BUILDER_DOMAINS | A comma separated list of domain names that can be used as the domains to create sub domains in the application builder. | |
| BASEROW_FRONTEND_SAME_SITE_COOKIE | String value indicating what the sameSite value of the created cookies should be. | lax |
| BASEROW_FRONTEND_COOKIE_PREFIX | Optional prefix added to frontend cookie names. Set a unique value per same-host instance, for example when running multiple local instances on different ports, because browser cookies are not isolated by port. | |
| BASEROW_DISABLE_SUPPORT | Set to any value to disable the support features in Saveroom. |
SSO Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_ALLOW_MULTIPLE_SSO_PROVIDERS_FOR_SAME_ACCOUNT | By default Saveroom will show a "please use the provider that you originally signed up with" error if you attempt to login to an email which has been already registered in your Saveroom server with a different SSO provider/authentication method. This is to increase the security of your Saveroom server. However, if you wish to allow a user who for example signed up initially using email and password to now login using a new SSO provider, and are comfortable with the increased risk of allowing this, then set this environment variable to any non empty value to disable this check. When turned on this environment variable will allow a Saveroom account to be logged into by any available authentication method and not just the first one that particular user signed up with. If you later turn off this environment variable by removing it, users who have previously logged into their account with multiple different providers will be able to continue to use all of those providers to login, however any new users will be forced to use the first provider they signed up with. | |
| BASEROW_OIDC_ONLY | When set to a truthy value, makes the instance OIDC-only for normal users: self-service (password) signup is disabled, password login is refused for non-staff accounts, and the login page hides the password form and signup, showing only OIDC buttons. A staff/superuser break-glass admin can still log in with a password by clicking "display password login" on the login page — a documented escape hatch in case the IdP is unavailable. | false |
| BASEROW_OIDC_PROVIDERS | A JSON list declaring the OpenID Connect providers users can sign in with. Each provider is an object with name (a stable url-safe slug used in the callback URL and shown per provider), issuer (the provider base URL, from which /.well-known/openid-configuration is discovered), client_id and client_secret. Optional keys: display_name (button label, defaults to name), scopes (defaults to ["openid", "email", "profile"], must include openid), email_claim (defaults to email) and name_claim (defaults to name). Access is derived from the IdP's client roles. roles_claim is the (dotted) claim path holding them and defaults to Keycloak's own resource_access.${client_id}.roles, with ${client_id} substituted for this provider's client id; a literal dot in a claim name is escaped as \.. Roles are read from the ID token and the userinfo response, so the client-roles mapper must be enabled on both — see the RHBK/Keycloak guide. Global-role mapping: staff_roles (client roles whose holders are granted global staff) and superuser_roles (granted global superuser). These are reconciled on every login — granted when the user holds a mapped role, revoked when not; a local admin that never logs in via OIDC is unaffected. user_roles lists the client roles whose holders may sign in as regular users. Workspace members, workspace admins, teams and database/table access are managed in the app, never by the IdP. Deny by default: when a provider maps any client role (user_roles, staff_roles or superuser_roles), a user holding none of them is refused at login (errorNoMappedRole) and no account is provisioned. A provider that maps no role at all is not gated and stays a plain sign-in provider. session_lifetime_minutes (default 480) bounds a session started through the provider: the user must sign in again once it ends, which is when role changes are applied; null falls back to BASEROW_REFRESH_TOKEN_LIFETIME_HOURS. require_verified_email (default true) refuses users whose email_verified claim is not true (errorEmailNotVerified), since accounts are linked by email. The login always uses PKCE (S256) and verifies the returned state and that the userinfo sub matches the ID token. An invalid configuration fails fast at startup, including the retired groups_claim / staff_groups / superuser_groups keys and the removed workspace_mappings / team_mappings / strict_membership keys. Configure the callback/redirect URL in your IdP as <BASEROW_PUBLIC_URL>/api/sso/oidc/callback/<name>/. Example: [{"name": "rhbk", "display_name": "Keycloak", "issuer": "https://keycloak.example.com/realms/main", "client_id": "baserow", "client_secret": "the-secret", "user_roles": ["baserow-user"], "staff_roles": ["baserow-admins"]}]. Full reference and a complete example: Single sign-on with OpenID Connect. |
[] |
Captcha Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_ENABLE_CAPTCHA | Set to all to enable captcha verification on all supported pages (currently only signup). You can also provide a comma-separated list of specific contexts like signup to enable captcha only in those places. Leave empty to disable captcha entirely. |
|
| BASEROW_CAPTCHA_PROVIDER | The captcha provider to use. Currently only cloudflare_turnstile is supported. |
cloudflare_turnstile |
| BASEROW_CLOUDFLARE_TURNSTILE_SITE_KEY | The Cloudflare Turnstile site key (public). Obtain this from the Cloudflare dashboard under Turnstile widget management. | |
| BASEROW_CLOUDFLARE_TURNSTILE_SECRET_KEY | The Cloudflare Turnstile secret key (private). Obtain this from the Cloudflare dashboard under Turnstile widget management. This key is used for server-side token validation and must be kept secret. |
ghcr.io/carneirofc/baserow Image only Configuration¶
| Name | Description | Defaults |
|---|---|---|
| NO_COLOR | Set this to any non empty value to disable colored logging in the all-in-one baserow image. | |
| DATA_DIR | For the all-in-one image only, this controls where Saveroom will store all data that needs to be persisted. Inside this folder Saveroom will store - Its postgres database - Redis database - Any autogenerated secrets like the django SECRET_KEY, the postgresql database user password and the redis user password - Caddy will store its state + any certificates and keys it uses during auto https |
|
| DISABLE_VOLUME_CHECK | For the all-in-one image only setting this to any non empty value will disable the check it runs on startup that the “/baserow/data/” directory is mounted to a volume. |
Build metadata¶
These identify the source a running instance was built from, which the version number alone cannot: the version tracks the upstream Baserow codebase, while these track this fork's release tag and commit. They are shown in the interface — on the login screen, in the user menu, and on the admin settings and health pages.
The published images already carry them: .github/workflows/build-publish-image.yml
passes all three as docker build arguments to the backend, web-frontend and all-in-one
builds, so nothing needs configuring for a normal deployment. Set them yourself only when
you build your own images, or to correct what an image reports without rebuilding it —
pass them to the backend and the web-frontend service, which each report their own
build. Leave them unset rather than empty: the backend reads an empty value as a
development build and reports nothing. The web-frontend keeps whatever was baked into its
image when the variable is empty, so an orchestrator that forwards unset variables cannot
blank it out, but it also means an empty value will not clear a stale one — rebuild or
pass a real value instead.
| Name | Description | Defaults |
|---|---|---|
| BASEROW_BUILD_VERSION | The release tag the instance was built from, for example v0.15.0. |
|
| BASEROW_BUILD_COMMIT | The full git commit hash the instance was built from. | |
| BASEROW_BUILD_DATE | When the image was built, as an ISO 8601 timestamp, for example 2026-09-18T10:34:30Z. |
A backend and a web-frontend reporting different commits means only half of a deployment was upgraded; the admin settings and health pages say so explicitly when that happens.
Plugin Configuration¶
| Name | Description | Defaults |
|---|---|---|
| BASEROW_PLUGIN_GIT_REPOS | A comma separated list of plugin git repos to install on startup. | |
| BASEROW_PLUGIN_URLS | A comma separated list of plugin urls to install on startup. | |
| BASEROW_DISABLE_PLUGIN_INSTALL_ON_STARTUP | When set to any non-empty values no automatic startup check and/or install of plugins will be run. Disables the above two env variables. | |
| BASEROW_PLUGIN_DIR | INTERNAL Sets the folder where the Saveroom plugin scripts look for plugins. | In the all-in-one image /baserow/data/plugins, otherwise /baserow/plugins |
Instance settings¶
A few settings are stored in the database rather than in the environment, and are changed
at runtime from Admin → Settings (/admin/settings) by an account with global staff
permissions. They need no restart and are shared by every backend and worker process.
Among them are four per-application-type switches — enable_database, enable_builder,
enable_dashboard and enable_automation — which turn a kind of application off for the
whole instance. See Turning application types off instance-wide.