Location of the configuration file
docassemble reads its configuration directives from a YAML file,
which by default is located in
If you are using Docker and S3 or Azure blob storage,
docassemble will attempt to copy the configuration file from your
S3 bucket or Azure blob storage container before starting.
How to edit the configuration file
The configuration file can be edited through the web application by
any user with
admin privileges. The editing screen is located on
the menu under “Configuration.” After the configuration YAML is
saved, the server is restarted.
You can also edit the configuration file directly on the file system. (You may need to be able to do so if you make edits to the configuration file through the web application that render the web application inoperative.)
Sample configuration file
Here is an example of what a configuration file may look like:
debug directive to
True on development servers. The default is
True enables the following features:
- The “Source” button in the web app, which shows the YAML source code used to generate the current question, an explanation of the path the interview took to get to the current question, and readability statistics for the question and the help text.
- Viewing LaTeX and Markdown source in document attachments.
root directive if you have configured docassemble to run
from a sub-location on your web server. The default is
The value of
root depends on how you configured your web server
during installation. If the WSGI application runs from the URL
use a trailing slash.
If the WSGI application runs from the root of your web server (e.g.,
https://docassemble.example.com/), do not set this directive, or set
The optional directive
url root indicates the part of the URL that
comes before the
It is normally not necessary for docassemble to know how it is being accessed from the web, because the URL is provided to the web application with every HTTP request.
However, there are some circumstances when docassemble code runs
outside the context of an HTTP request. For example, if you have a
scheduled task that uses
send_sms() to send a text message with
a media attachment, the URL for the media attachment will be unknown
unless it is set in the configuration.
dispatch directive allows users to start interviews with
user-friendly URLs like
If you define the
dispatch directive, your users can see a list of
available interviews by going to the URL
/list on the site.
The title of this page is configurable with the
start page title
The icon in the browser tab is known as a favicon. This is the icon associated with the web application. By default, docassemble uses the docassemble logo for this icon.
If users “pin” your application to their device’s main menu, this icon will be used to create the resulting icon. Microsoft, Apple, and Google have their own conventions for doing this.
In order to “brand” your application in a custom way, create a square logo and go to http://realfavicongenerator.net in order to generate favicon files from it. Upload a square image that is at least 512x512 in size. In addition to uploading your file, you will need to make some choices about different colors that should be used in different circumstances. At the end, you will download a Zip file containing a number of graphics files and other files.
Put the contents of this Zip file in a folder in a docassemble
package and then add a
favicon directive to the configuration,
pointing to this folder. For example:
In this example,
data/static/favicon in the
docassemble.abcincorporated package is a folder that is expected to
contain the following files, which were contained in the Zip file:
In addition to providing you with a Zip file containing the above
files, the above web site will instruct you to place particular
<meta> tags in the HTML of your site. docassemble
does this for you automatically, so you can ignore most of this.
However, two of the lines are important. The will look like this:
color in the first line and the
content in the second
line. Then add the following two lines to your configuration,
corresponding to the above two lines:
If you do not specify
favicon mask color or
favicon theme color,
your custom favicon will still work, but docassemble will choose
colors for you. (The colors above are the defaults.)
Note that if you have set the
root directive (if your
docassemble site at
https://example.com/something/ instead of
https://example.com/), you will need to account for this when you
generate the favicon files using the above web site. This is
important because the
contain URL references. If your site is at
manifest.json will need to refer to
"/something/android-chrome-192x192.png" instead of
Note that most web browsers will store a cache of the Favicon, so that when you make a change to your app’s Favicon, it may seem that your change is not working when it actually is. If it seems that your Favicon has not taken effect, try accessing the app a web browser that you do not normally use.
db section of the configuration tells the docassemble web
app where to find the SQL database in which to store users’ answers,
login information, and other information.
docassemble will connect to the SQL database
at the hostname
host on the port
port, and will authenticate with
password. It will connect to the database called
name. If you want separate docassemble systems to share the
same database, you can set a
schema file directive helps
docassemble create missing columns during the startup process. It
is used by the
during Docker startup and during installation and upgrades.
brandname directives control the name of the
application in various contexts.
On administration pages, the
appname appears in the web browser tab,
brandname appears in the navigation bar.
appname is also used in e-mails that are generated by the
user login system.
appname defaults to
brandname will default
brandname is not specified.
default title and
default short title directives control the
names that are displayed in the web browser tab and the navigation bar
of interviews that do not specify these titles in their
The “short” title appears on mobile devices, while the long title appears on larger screens.
If not specified, the
default title will default to the
uploads directive indicates the directory in which uploaded files are stored.
The default value is
packages directive indicates the base directory into which
docassemble extension packages will be installed. The
PYTHONUSERBASE environment variable is set to this value and pip
is called with
--install-option=--user. When Python looks for
packages, it will look here. Python’s default value is
but docassemble changes it to the value of this directive, or
/usr/share/docassemble/local if the directive is not defined.
webapp directive indicates the path to the WSGI file loaded by
the web server.
docassemble needs to know this filename because the server needs to reset itself after an add-on package is updated. The web server is reset by updating the modification time of the WSGI file.
The default value is
certs directive indicates a central location where SSL
certificates for the web server can be found. The location can be a
file path, an S3 path, or an Azure blob storage path. This is
only relevant if you are using HTTPS.
For example, you might keep your certificates on a network drive:
By default, the Apache HTTPS configuration contains:
When using a multi-server arrangement or Docker, the supervisor
process on each web server executes the
docassemble.webapp.install_certs module during the
startup process. This module copies certificates from the location
/etc/ssl/docassemble before starting the web
server. This is a convenience feature. Otherwise, you would have to
manually install the SSL certificates on every new docassemble web
server you create.
The value of
certs can be a file path, an Amazon S3
s3://exampledotcom/certs), or an
Azure blob storage URI (e.g.,
blob://youraccountname/yourcontainername/certs). The contents of
the directory are copied to
Here is an example. Install
s3cmd if you have not done so already:
s3 configuration has
bucket: yourbucket, then you do not
need to set a
certs configuration, because docassemble will by
default look in
s3://yourbucket/certs. However, if the certificates
are stored in another location, you can specify a different location:
If you want to use a location other than
can change the
cert install directory setting (see below). You will
also, of course, need to change the web server configuration file.
docassemble needs to send e-mail, for example to reset people’s passwords, or to let users of a multi-user interview know that it is their turn to start answering questions.
By default, docassemble assumes that an SMTP server is installed on the same machine as the web server and that it uses port 25.
To use another SMTP server as the mail server, do something like:
If you are hosting docassemble in the cloud, you will probably have to use a separate SMTP server in order to send e-mail.
A free option is Mailgun. You can sign up with Mailgun, provide a credit card (which will only be charged if you exceed the free tier), configure some DNS entries, and then set your configuration to something like this:
If no interview is specified in the URL when the web browser first
connects to the docassemble server, the interview indicated by
default interview will be used. The interview needs to be specified
in “package name:relative file path” format. For example:
If this directive is not set, docassemble will redirect to a page
showing a list of available interviews determined by the
dispatch directive. However, if the
dispatch directive is not
defined, users will be directed to the demonstration interview,
docassemble uses the Flask web framework. The
flask log and
celery flask log directives contain the paths to the Flask log
files for the web application and the Celery background workers,
respectively. Most errors write to the
docassemble.log file located
/usr/share/docassemble/log (or the directory indicated by
log, or to standard web server error logs, but there are some
errors, typically those that are Flask-related, that will only write
to these log files.
The default locates for the Flask log files are
These directives set the default language and locale settings for docassemble interviews.
The dialect is only relevant for the text-to-speech feature, which is
controlled by the special variable
speak_text. See the
voicerss configuration for more information about configuring this
feature. The default dialect is only used as a fallback, in case the
dialect cannot be determined any other way. It is better to set the
set_language() or the
country directive sets the default country for docassemble.
The country is primarily relevant for interpreting telephone numbers. The code needs to be a valid country code accepted by the phonenumbers library.
If you are using Docker, the
os locale directive will set the
default operating system locale.
If your interviews use locale and language settings that your operating system does not support, you will get an error.
These packages will be installed when the Docker container starts.
When a docassemble SQL database is first initialized, an
administrative user is created. By default, this user has the e-mail
[email protected] and the password
password. As soon as the
web server comes on-line, you can log in and change the e-mail address
and password to something more secure.
However, you can also use the
default admin account directive in the
configuration so that a more secure e-mail address and password are
used during the setup process.
The settings are only used by the
module during the initial setup process. Using the information
defined here, that script sets up a single account in the
user login system with “admin” privileges.
create_tables runs for the first time, you can delete the
default admin account information from the configuration file.
The Flask web framework needs a secret key in order to manage
session information and provide protection against
cross-site request forgery. Set the
secretkey to a random value
that cannot be guessed.
password secretkey is used in the process of encrypting
interview answers for users who log in using
Facebook, Google, or Azure. It defaults to the same value as
secretkey. If this value changes, users who log in through
Facebook, Google or Azure will not be able to resume stored
When users supply PDF files and docassemble includes those files
within a document, the PDF pages are converted to PNG images in
order to be included within RTF files. The
png resolution directive
defines the dots per inch to be used during this conversion.
PDF files are also converted to PNG for previewing within the web app,
but at a lower resolution. The
png screen resolution directive
defines the dots per inch to be used for conversion of PDF pages to
PNG files for display in the web browser.
If you use the
ocr_file() function, the pages of the PDF file will
be converted to images before being read by the OCR engine. By
default, the resolution used is 300 dpi. To change this to something
else, set the
ocr dpi directive:
show login directive is set to
False, users will not see a
“Sign in or sign up to save answers” link in the upper-right-hand
corner of the web app.
The default behavior is to show the “Sign in or sign up to save answers” link.
allow registration directive is set to
False, users will
not be allowed to register to become users of the site unless they are
invited by an administrator.
The default behavior is to allow any user to register.
If you want to verify e-mail addresses of users, you can set the
email confirmation privileges directive to a list of privileges for which
e-mail confirmation should be a requirement of logging in.
By default, e-mail confirmation is not required for any privileges (i.e.,
email confirmation privileges is an empty list. Also, the default
administrative user is confirmed when initially created, so you will
never need to confirm that user’s e-mail.
Before you enable this feature, make sure you have a working email configuration.
If your web server is not configured to support X-SENDFILE headers,
xsendfile directive to
Use of X-SENDFILE is recommended because it allows the web server, rather than the Python WSGI server, to serve files. This is particularly useful when serving sound files, since the web browser typically asks for only a range of bytes from the sound file at a time, and the WSGI server does not support the HTTP Range header.
docassemble writes messages to a log files stored in the directory
indicated by the
log directive. These messages are helpful for
debugging problems with interviews.
The default directory is
log server is set, docassemble will write messages to TCP
port 514 on that server, and will not write to the
When the scheduled tasks feature is enabled on the server,
docassemble will delete interviews after 90 days of inactivity.
To change the number of days, set the
interview delete days
directive in the configuration. For example:
interview delete days is set to
0, interviews will never be
deleted through scheduled tasks.
By default, the user interface polls the server every six seconds to “check in” to see if anything has happened that it needs to know about, and to let the server know that the user is still active.
You can change this interval by setting the
directive. The number refers to the milliseconds between each call to
The default value is
This directive only has an effect during initial database setup.
Pre-defined variables for all interviews
If you would like to pass variable definitions from the configuration
into the interviews, you can set values of the
Then, in all of the interviews running on the server, you can include things like:
If your server will offer interviews in languages other than English, you will want to make sure that built-in words and phrases used within docassemble, such as “Continue” and “Sign in,” are translated into the user’s language.
words directive loads one or more YAML files in order:
Assuming the following is the content of the
data/sources/words.yml file in
then if the interview calls
set_language('es') (Spanish) and
docassemble code subsequently calls
word('Help'), the result
When you are logged in as a developer or administrator, you can go to the “Utilities” page from the main menu, where you will find a utility for generating a draft YAML file for translating all of the words and phrases that docassemble uses and that might be presented to the user. If you have set up a Google API key, it will use the Google Cloud Translation API to prepare “first draft” translations for any ISO-639-1 language you designate.
You can set a default currency symbol if the symbol generated by the locale is not what you want:
If you are using a multi-server arrangement you can reduce
bandwidth on your web server(s) by setting
fileserver to a URL path to
a dedicated file server:
Always use a trailing slash.
If this directive is not set, the value of
root will be used to
create URLs to uploaded files and static files.
Whether there will be a performance benefit to using a dedicated file server is not certain.
If you have a Google API key, you can include it as follows:
If the special variable
speak_text is set to
will present the user with an audio control that will convert the text
of the question to speech. This relies on the VoiceRSS web service.
You will need to obtain an API key from VoiceRSS and set the
configuration below in order for this feature to function. (The
service allows 350 free requests per day.)
enable key must be set to
True in order for the text-to-speech
feature to work. The
key is the VoiceRSS API key. The
languages key refers to a dictionary that associates languages with
default dialects to be used with that language.
ocr_file() function uses the Tesseract
optical character recognition (OCR) application to extract text from
image files and PDF files. One of the options for the OCR process is
the language being recognized. The codes for language that
Tesseract uses are different from those that docassemble uses.
In most cases, the code that Tesseract uses is the ISO-639-3 code
that corresponds to the ISO-639-1 code that docassemble uses,
and docassemble can make this conversion automatically. However,
in some cases this does not work, so there is an override, which is
controlled by the
ocr languages directive. The default value maps
Chinese to Traditional Chinese:
If all of the Chinese documents that you want to OCR are written in Simplified Chinese, and all the Uzbek documents are written in Cyrillic, you could set the following:
For more information, see the documentation of the
You will need to create the bucket before using it; docassemble will not create it for you.
If you are using Azure blob storage to store shared files, enter your account name, account key, and container name as follows:
You will need to create the container before using it; docassemble will not create it for you.
This is necessary because when docassemble runs in a
multi-server arrangement, each docassemble web server instance
needs to allow other docassemble web instances to send messages to
it through supervisor. Each web server instance advertises the
hostname or IP address through which its supervisor can be accessed.
Normally, this can be obtained using the computer’s hostname, but
within an EC2 instance or Docker container, this hostname is not
one that other web servers can resolve. If
ec2 is set to
then docassemble will determine the hostname by calling
ec2 is set to
True, docassemble will determine the hostname
this URL does not work for some reason, but a different URL would
work, you can change the URL that docassemble uses by setting the
ec2 ip url configuration item.
phone login is set to
True, then docassemble will allow
users to log in with a phone number. For this system to work, the
twilio configuration must be set up. The user needs to put in his
or her phone number, and then a random verification code will be sent
to that phone number via SMS. The user needs to type in that code
in order to log in. As with the
external authetication methods, registration happens
automatically upon the first login. Subsequent logins will also
require entering a random verification code.
The details of how this login system functions, such as the number of digits in the verification code and the number of seconds that the code remains valid, can be configured.
For added security, you can allow users who log in with passwords to
enable two-factor authentication on their accounts. The two-factor
authentication system can use Google Authenticator, Authy, or
another compatible app. Or, if you have set up a
configuration, the system can send a verification code to the user in
an SMS message.
To give your users the option of using two-factor authentication, set
two factor authentication to
True. Logged-in users will then see
an option on their “Profile” page for configuring two-factor
authentication. By default, only administrators and developers see an
option on their user profile to configure second-factor
authentication. To configure which privileges have the option of using
second factor authentication, set
two factor authentication privileges to
the full list of privileges you want to be able to use the feature.
external hostname is the hostname by which users will access
docassemble. This variable is only used if docassemble is
running on Docker.
behind https load balancer directive to
True if you are
running docassemble in a configuration where docassemble
itself is running HTTP, but requests are being forwarded to it by a
server running HTTPS. This might be your configuration if you are
using a load balancer or you are running Docker on machine that
forwards HTTPS requests to Docker on a non-standard HTTP port.
If you use the e-mail receiving feature, set the
domain to whatever e-mail domain will direct e-mail to the
docassemble server configured to perform the
interview_email() function will then return an e-mail address
@mail.example.com at the end.
incoming mail domain is not specified, the value of
external hostname will be used.
cert install directory directive indicates the directory where
the web server expects SSL certificates to reside. By default, this
/etc/ssl/docassemble, but you can change it to wherever the web
server will look for SSL certificates. This is only applicable if you
are using HTTPS.
In a multi-server arrangement or Docker, a supervisor process
will run as root upon startup that will copy files from the
directory to the
cert install directory and set appropriate file
permissions on the certificates.
log server directive is set, docassemble will write log
messages to TCP port 514 on the hostname indicated by
instead of writing them to
/usr/share/docassemble/log/docassemble.log (or whatever other
directory is set in
redis directive needs to be written in the form of a
rabbitmq directive needs to be written in the form of an AMQP
By default, docassemble assumes that you have ImageMagick and
pdftoppm installed on your system, and that they are accessible
through the commands
pdftoppm, respectively. If you
do not have these applications on your system, you need to set the
configuration variables to null:
If you have the applications, but you want to specify a particular path, you can set the path using the configuration variables:
By default, docassemble assumes that you have pacpl (the
Perl Audio Converter and/or avconv installed on your system, and
that they are accessible through the commands
avconv, respectively. If you do not have these applications on
your system, you need to set the configuration variables to null:
You can also set these variables to tell docassemble to use a particular path on your system to run these applications.
docassemble requires that you have Pandoc installed on your
system. It assumes that it can be run using the command
If you need to specify a different path, you can do so in the configuration:
By default, docassemble assumes that you have LibreOffice
installed on your system, and that it is accessible through the
libreoffice. If you do not have LibreOffice on your system,
you need to set the configuration variable to null:
You can also use this configuration variable to set a different path for the application. There are different versions of LibreOffice that go by different names:
as_datetime() that deal with dates will use a
default time zone if an explicit timezone is not supplied. If you set
timezone directive to something like
will be used as the default time zone. Otherwise, the default time
zone will be set to the time zone of the server.
You can also tweak the operation of docassemble’s interaction with PyPI by setting the following optional directives (which you should never need to do):
pypi url directive refers to the web site to use for publishing.
It should not have a trailing slash.
pypirc path directive refers to the file where the username and
password will be stored. You may need to edit this if you run
docassemble on a non-standard operating system.
If you want to enable logging in with Facebook, Google, or Microsoft Azure, you will need to tell docassemble your OAuth2 keys:
You can disable these login methods by setting
by removing the configuration entirely.
There are several features of docassemble that involve integration
with the Twilio service, including the
send_sms() function for
sending text messages, the text messaging interface for interacting
with interviewees through text messaging, and the call forwarding
feature for connecting interviewees with operators over the phone.
These features are enabled using a
twilio configuration directive.
Here is an example:
sms: True line tells docassemble that you intend to use the
text messaging features.
voice: True line tells docassemble that you intend to use the
call forwarding feature.
account sid is a value you copy and paste from your Twilio
dispatch configuration allows you to direct users to different
interviews. For example, with the above configuration, you can tell
your prospective users to “text ‘color’ to 276-241-0114.” Users who
initiate a conversation by sending the SMS message “help” to the
Twilio phone number will be started into the
default interview configuration allows you to set an interview
that will be used in case the user’s initial message does not match up
dispatch entry. If you do not set a
default interview, the
default interview will be used. If you want unknown
messages to be ignored, set
default interview to
You can use multiple Twilio configurations on the same server. You
might wish to do this if you want to advertise more than one Twilio
number to your users. You can do this by specifying the
directive as a list of dictionaries, and giving each dictionary a
name. In this example, there are two configurations, one named
default, and one named
When you call
send_sms(), you can indicate which configuration
should be used:
This will cause the message to be sent from 276-857-1217.
If no configuration is named
default, the first configuration will
be used as the default. The call forwarding feature uses the
By default, users who unsuccessfully log in are blocked after 10
failed attempts. This threshold can be configured with
The time period for blocking defaults to 86,400 seconds (one day).
The number of seconds of blocking can be configured with
When you use the phone login feature, the user needs to enter a 5
digit code that they receive via SMS. The number of digits in this
code can be configured with
verification code digits. The code is
only valid for a limited period of time. This period of time defaults
to 180 seconds and is configurable with
verification code timeout.
get_config() will return
None if you ask it for a value that does
not exist in the configuration.
The values retrieved by
get_config() are the result of importing the
YAML in the configuration file. As a result, the values may be
text, lists, or dictionaries, or any nested combination of these
types, depending on what is written in the configuration file.
It is a good practice to use the configuration file to store any sensitive information, such as passwords and API keys. This allows you to share your code on GitHub without worrying about redacting it first.
Using a configuration file in a different location
If you want docassemble to read its configuration from a location
/usr/share/docassemble/config.yml, you can set the
DA_CONFIG_FILE environment variable to another file location. You
might want to do this if you have multiple virtual hosts, each running
a different WSGI application on a single server.
Note that the configuration file needs to be readable and writable by the web server, but should not be readable by other users of the system because it may contain sensitive information, such as Google and Facebook API keys.