Site configuration

This chapter describes the configuration options for your sites. There’s also global configuration.

Site config locations

Configuration for sites is stored:

  • in a priv/zotonic_site.config file in the site directory
  • optionally, in files in the site’s priv/config.d/ directory. This is so that automated provisioning tools can easily override site configuration.

The config.d files will extend and/or override the configuration options from the zotonic_site.config file. So if the same key is present in both zotonic_site.config and config.d/some-file, the value from some-file will be used. The files under config.d/ are read in alphabetical order.



The password for the admin user:

{admin_password, "top_secret"},

Note that if the admin_password is set to admin then only clients with local network addresses can logon as the admin. See also ip_allowlist below.


Database host that the site connects to. Example:

{dbhost, ""},

Defaults to the dbhost in the Zotonic config. Which defaults to


Port of the database server. Example:

{dbport, 5432},

Defaults to the dbport in the Zotonic config. Which defaults to 5432.


Database user. Defaults to the dbuser in the Zotonic config. Which defaults to zotonic.


Database password. Defaults to the dbpassword in the Zotonic config. Which defaults to zotonic.


Database name. Use none to run Zotonic without a database:

{dbdatabase, none},

Defaults to the database configured in the Zotonic config (which defaults to zotonic).

If the dbuser does not have permission to create the database then you have to create it yourself:

CREATE DATABASE "some_database" ENCODING = 'UTF8' TEMPLATE template0;
GRANT ALL ON DATABASE some_database TO some_db_user;

Where some_db_user must be the user you configured with dbuser and some_database must be the database configured with dbdatabase.


PostgreSQL Database schema. Defaults to either:

  • the name of the site if the dbdatabase is the default database from the zotonic config
  • public if the dbdatabase is set to something else than the default from the Zotonic config.

So if you configure a special database for your site then the default schema will be public.


{dbschema, "mysiteschema"},

In Zotonic, a single PostgreSQL database can host the data of multiple sites. This does not work using table prefixing, but instead, Zotonic uses PostgreSQL’s native feature of database schemas.

A database schema is basically another database inside your database. If your dbuser does not have permission to create the schema, then you will need to create any schema other than public first:

CREATE SCHEMA some_site;
GRANT ALL ON SCHEMA some_site TO some_db_user;

Where some_db_user must be the user you configured with dbuser. After creating the schema, either restart the site or restart Zotonic.


Maximum number of database connections used by the site. Unused connections are closed after some time.

This parameter should be enlarged if the following error occures frequently:

Database pool usage is close to exhaustion, please increase the pool size.

And definitely increase the pool size if this error occurs frequently:

Database pool is exhausted, please increase the pool size.

The default is 20 connections:

{db_max_connections, 20},


The maximum amount of memory a site may take (in MB). The depcache caches various results of function calls and database queries in memory. Example:

{depcache_memory_max, 100},


The hostname and port part of the site URL. This is used to determine to which site an incoming request should be routed. Example:

{hostname, ""},

Note that the hostname does not specify on which port Zotonic will listen; this is configured globally.


A list of alias hostnames for the site. By default, Zotonic redirects these to hostname (see redirect). Example:

{hostalias, [


Whether or not to redirect the host-aliases (listed by the hostalias directives) to the main hostname. Defaults to true, to prevent content duplication: it is good web practice to let your content live on a single URL only:

{redirect, true},


Set by the zotonic addsite command, this settings tells Zotonic which skeleton site to use. Example:

{skeleton, blog},


Creates the initial main menu when installing mod_menu. A menu item is an Erlang tuple with a resource name and list of child menu items (if any): {name, []}. Example:

{install_menu, [
    {page_some_thing, []},
    {page_some_other_thing, []},
    {page_one_more_thing, []}


List of all modules that are activated when the site is started. After adding a module here, restart the site to load the module. Example:

{modules, [


List of TCP/IP addresses and their netmasks. The default admin user password (“admin”) will only be accepted for an IP in the allowlist. This protects development systems that are exposed to the internet. This can also be configured globally. Default:

{ip_allowlist, ",,,,::1,fd00::/8"}


Hostname you want e-mail messages to appear from. See E-mail handling.


The domain the Zotonic session-id and page-id cookies will be set on. Defaults to the main hostname.


Override the default zotonic installer (z_installer). <module> should make sure that the database, if used, is setup properly along with any required data. Note that it is z_installer that is processing the install_modules and install_menu options, so if this module is not used then those menus and modules will not be installed unless the new module performs those operations. Example:

{installer, your_installer_erlang_module},

Setting module-specific config values in the site config

It is also possible to add m_config values for modules to the site’s sitename/priv/zotonic_site.config file. To do this, add clauses like this to the site’s config:

{mod_foo, [{key, value}, ...]}

Using environment variables in the site config

Any variable in your site’s zotonic_site.config file can be retrieved from the OS environment variables. To do so, wrap the config value in a {env, ...} tuple. For instance, to use the DB_HOST environment variable as the database host, put the following as the dbhost config value:

{dbhost, {env, "DB_HOST"}},

Besides {env, "NAME"} tuple, you can also specify {env, "NAME", "default value"} for the case the environment variable is not set:

{dbhost, {env, "DB_HOST", "localhost"}},

To convert environment variables to integer (e.g. for the database port), use env_int:

{dbhost, {env_int, "DB_PORT"}},

or, with default value:

{dbhost, {env_int, "DB_PORT", "5432"}},

Note that the default value needs to be a string in this case, not an int.

Edit on GitHub

Global configuration Configuration Port configurations

Referred by


Retrieve information that is stored in the site configuration. If you want to query values from the config table…


Modules are the building blocks of Zotonic. They add functionality to your Zotonic website such as:


mod_search implements various ways of searching through the main resource table using m_search.

Global configuration

This section describes the location and contents of Zotonic’s global configuration files erlang.config and zotonic.


Zotonic has the capability of serving more than one site at a time. You can have multiple sites enabled, each with its…


Zotonic has two places where a site’s configuration is kept: