Configuring server options
Björn Rydahl avatar
Written by Björn Rydahl
Updated over a week ago

Configuring server options

Config options are used to enable or disable certain features or behaviour in ftrack. They are specified on the ftrack server in /opt/ftrack_config/ftrack.ini under the [DEFAULT] section. After modifying the config file, ftrack service must be stopped and started again, for the changes to apply.

Service secret

A service secret is required to have internal services working properly. A secret needs to be generated and added to the ini file.

ftrack.service_secret = SOME_SECRET

The secret should be random and at least 36 characters long. A secret can be generated like this:

python -c 'import uuid;print uuid.uuid4()'

Server URL

The server URL needs to be set to let ftrack know what URL your users will be using to connect to the server. The URL is used to generate emails correctly and ensure some of the internal services are working properly. The URL should contain protocol.

ftrack.server_url = http://my-company-ftrack

The URL must be accessible from the ftrack server as it will also be used for internal communication.


Email settings should be configured to allow the ftrack server to send out notifications via email.

# Turbomail config.
mail.on = true
mail.transport = smtp
mail.smtp.server = YOUR-SMTP-SERVER_URL:PORT
mail.encoding = utf-8
mail.smtp.username = USERNAME
mail.smtp.password = PASSWORD = ftrack <>

You can also configure ftrack to send error emails when a server error happens using:

# Error email config.
error_email = (address where error mail should be sent)
from_address = ftrack
smtp_username = USERNAME
smtp_password = PASSWORD

If TLS is in use, please add the following parameter:

smtp_use_tls = true

Note: We recommend that you track errors with sentry instead of via emails.

Tip: You can test sending emails from the ftrack diagnostics page in system settings. Either to your user, or by triggering a server error which will send to the error email config.

2-factor authentication

2FA is enabled by default on local installations, but to be able to use it a secret key must be configured. If this key changes after users have configured 2FA on their accounts, their time based 2FA codes will no longer work and must be reconfigured. Generate a secret using the following command:

python -c 'import uuid;print uuid.uuid4()'

Then add it to the ftrack.ini file as:

ftrack.2fa_secret = SOME_SECRET

Note: Do not use the same key for 2FA as for the service secret, they should be unique.


FFMPEG encoding resolution and bitrate can be configured. Default max resolution is 720 and bitrate is 2000. Both settings are integers.

ftrack.ffmpeg_video_resolution = 1080
ftrack.ffmpeg_video_bitrate = 3000

PDF export font

Specify the font file that should be used when exporting a PDF.

ftrack.pdf_export_font_path = /ABSOLUTE_PATH_TO_FONT/FONT.ttf

Note: The path have to be an absolute path and the font must be in ttf format.

Custom layouts

Specify a folder with JSON configuration files.

The configuration files are loaded when the server starts. To apply new changes, the server needs to be restarted.

ftrack.form_layout_path = /PATH/TO/FOLDER/WITH/LAYOUTS

Due date in Tasks widget

Enable due date column in Tasks widget in sidebar.


Configure Web server

The main ftrack server is using uWSGI which has a lot of configuration options that can be used to tune ftrack for better performance.

Always use a staging server when tuning ftrack to test various options before deploying in production.

The default options are passed to uwsgi when it is started but can be overridden in the ftrack ini file by adding a uwsgi section:

processes = 15

By default ftrack will use 10 processes and that should be enough for most scenarios. Each process have 10 threads that are responsible of serving requests. Increasing the number of processes will allow the ftrack server to serve more requests at the same time.

Each process will consume additional RAM which may increase slightly over time. There is also a certain ratio between number of CPUs on your server and the number of processes that make the server efficient. As an example, having 2 CPU cores and 20 processes is likely not going to result in better performance when the number of concurrent requests against the server is high.

If you are running the database on the same server you should make sure you never run out of RAM since that will likely result in the database failing to allocate memory and crash.


Tuning a server is not an exact science as it depends on a lot of factors. Keep an eye on CPU usage and disk IO when tuning your server to get an idea of what is the main bottleneck. There are a few tools that can be used to monitor the processes and the number of requests they serve.


/opt/ftrack/environments/ngxtop/bin/ngxtop -l /tmp/ftrack_nginx.log

Can be used to monitor all requests passing through Nginx and look at their response codes in real time. ngxtop parses the access log and can also be used to look and past requests like this:

/opt/ftrack/environments/ngxtop/bin/ngxtop -l /tmp/ftrack_nginx.log --no-follow


The processes running in uWSGI can be monitored individually to ensure they are serving content properly using:

/opt/ftrack/environments/uwsgi/bin/uwsgitop /tmp/uwsgi_stats.sock

Track exceptions with sentry

Sentry can be used to capture exceptions happening in ftrack to see when and how often they occur. To capture exceptions with sentry the ftrack.ini file needs to be updated with the following:

ftrack.sentry = true

To use sentry on your local install you need to have a sentry account and there you can find your sentry dsn.

You can also use sentry to track exception which occur in client-side applications by creating a new project in Sentry and adding the corresponding public DSN key to the configuration file.

ftrack.sentry_dsn_ftrack_spark_overview = https://...

Fetch update events directly from internal queue

Please note that this is an advanced feature which requires you to setup and and run your own broker instead of the one bundled with ftrack. Once you have your own rabbitmq server running you can update the ftrack.ini "ftrack.amqp_host" setting to have ftrack use that server instead.

Update events can be listened to using the event hub in the API. Sometimes it is useful to get the events directly from the internal events queue to guarantee that no events are missed due to dropped connections or similar between the API and the event server.

For this to work, the event server must enable use of the amqp messaging queue via the configuration option:

ftrack.enable_amqp_event_server = true

When an event is generated on the ftrack server it is added to the amqp messaging queue via an exchange called ftrack-events. The ftrack event server will register a queue bound to that exchange called ftrack-event-server-queue and use that to process the events. If you want to gather the events directly from the amqp messaging queue you can register your own queue via the same exchange and read the events from there. This ensures that events are never missed even if your script is restarted.

Override the default create project behavior

You can override the default behavior when a user chooses to create a new project to invoke an action instead of displaying the default dialog:

# Set to an action identifier to be launched when creating a project
ftrack.create_project_action_identifier =

An minimal example action which creates a project is available here:

Cookie sessions

Encrypted client side cookie based sessions can be used instead of file based sessions with ftrack. The client side sessions will not store session files on the ftrack server which is useful when scaling out as ftrack can be run on multiple servers and still share sessions and also avoids hitting inode limit on the server. Read more about the beaker session configuration options in the beaker documentation.

beaker.session.key = ftserver
beaker.session.type = cookie = true # Only set if using https.
beaker.session.cookie_expires = false
beaker.session.httponly = true
beaker.session.validate_key = <A SECRET KEY>
beaker.session.encrypt_key = <ANOTHER FAIRLY LONG SECRET KEY>

Memory usage

It may be difficult to estimate how much memory ftrack will use, and it may vary depending on how many processes you configure uwsgi to use. Some modules may also leak memory over time. If you database is running on the same server you may want to limit how much memory uwsgi can use:

lazy-apps = true
reload-on-rss = 1000
evil-reload-on-rss = 1500
worker-reload-mercy = 10

What are the options:

  • lazy-apps: Saves some memory on master process.

  • reload-on-rss: Soft memory limit for a uwsgi process in MB.

  • evil-reload-on-rss: Hard memory limit for a uwsgi process in MB.

  • worker-reload-mercy: Seconds a process will wait for current requests to finish before reloading.

Setting these options in the ftrack.ini file will give you a better estimate on how much memory will be used. With these settings uwsgi will likely not use more than (reload-on-rss * processes) MB, but having the evil-reload-on-rss set higher will allow for bursts when needed.

Did this answer your question?