Configuration

Introduction

Convos can be configured with either a config file or environment variables.

Any of the settings below can be specified either in a configuration file or as environment variables. Here is an example on how to specific environment variables:

You might want to check out the FAQ for example configurations as well.

$ CONVOS_INVITE_CODE=s3cret ./script/convos daemon

One way of setting a bunch of environment variables is by putting them all in a shell script:

#!/bin/sh
export CONVOS_CONTACT=[email protected]
export CONVOS_HOME=/var/convos
export CONVOS_INVITE_CODE=s3cret
export MOJO_LOG_LEVEL=debug

exec /home/www/convos-stable/script/convos \
  daemon --listen http://*:8000            \
  1>>/home/www/log/convos.log              \
  2>>/home/www/log/convos.log

Instead of using environment variables, you can specify configuration settings in a JSON config file. Note that all the settings below is optional, just like the environment variables.

$ /home/www/convos-stable/script/convos /path/to/convos.conf.json \
    --listen http://*:8000

$ cat /path/to/convos.conf.json
{
  "backend":           "Convos::Core::Backend::File",
  "contact":           "mailto:[email protected]",
  "default_server":    "localhost:6667",
  "log_file":          "/var/log/convos.log",
  "forced_irc_server": "localhost:6667",
  "invite_code":       "s3cret",
  "organization_name": "Awesome hackers",
  "plugins":           {},
  "secure_cookies":    0,
  "secrets":           ["signed-cookie-secret"]
}

Note: A config file can also be a plain Perl hash. If you want to use the perl format instead of JSON, then just drop the “.json” suffix on the file.

Listen

You can make convos listen to a variety of addresses:

# Listen on all IPv4 interfaces
$ ./script/convos daemon --listen http://*:8080

# Listen on all IPv4 and IPv6 interfaces
$ ./script/convos daemon --listen "http://[::]:8000"

# Listen on a specific IPv4 and IPv6 interface
$ ./script/convos daemon \
  --listen "http://127.0.0.1:8080" \
  --listen "http://[::1]:8080"

# Listen on HTTPS with a default untrusted certificate
$ ./script/convos daemon --listen https://*:4000

# Use a custom certificate and key
$ ./script/convos daemon --listen \
  "https://*:8000?cert=/path/to/server.crt&key=/path/to/server.key"

# Make convos available behind a reverse proxy
$ MOJO_REVERSE_PROXY=1 ./script/convos daemon \
  --listen http://127.0.0.1:8080

See MOJO_REVERSE_PROXY for more details about setting up Convos behind a reverse proxy.

Configuration parameters

CONVOS_BACKEND

Can be set to any class name that inherit from Convos::Core::Backend.

Default: Convos::Core::Backend::File

CONVOS_CONNECT_DELAY

This variable decides how many seconds to wait between each user to connect to a chat server. The reason for this setting is that some servers will set a permanent ban if you “flood connect”.

Default: 3

CONVOS_CONTACT

Used when rendering “Contact” links in the frontend.

Default: mailto:[email protected]

CONVOS_DEBUG

Setting this variable to a true value will print extra debug information to STDERR. Another useful debug variable is MOJO_IRC_DEBUG which gives you IRC level debug information.

CONVOS_DEFAULT_SERVER

Used to declare which server should be pre-filled when a user creates a new connection.

Default: localhost

CONVOS_FORCED_IRC_SERVER

Will force any connection made to use this server. Note that this environment variable also overrride CONVOS_DEFAULT_SERVER.

There is no forced IRC server by default.

CONVOS_HOME

This variable is used by Convos::Core::Backend::File to figure out where to store settings and log files.

Default: $HOME/.local/share/convos/

CONVOS_INVITE_CODE

The value of this setting need to be used by the person who wants to register. It can be disabled by setting CONVOS_INVITE_CODE="". Check out the running guide for more details.

The default value is a semi-random string.

CONVOS_LOG_FILE

This value can be used to specify where Convos should write the log messages to. This settings has no default value which makes Convos write the log to STDERR.

CONVOS_ORGANIZATION_NAME

Should be set to the name of the organization running this instance of Convos.

Default: Nordaaker

CONVOS_ORGANIZATION_NAME

This variable will change the URL to the organization running this instance of Convos.

Default: http://nordaaker.com

CONVOS_PLUGINS

A list (comma separated) of perl modules that can be loaded into the backend for optional functionality.

There are currently no plugins loaded by default.

CONVOS_SECRETS

Should be set to list (comma separated) of random strings. This value is used to secure the Cookies written to the client.

The default value is a semi-random secret.

CONVOS_SECURE_COOKIES

Should be set to true if Convos is served over HTTPS.

MOJO_CONFIG

Can hold the path to a config file, which is read by Convos instead of using the environment variables. See also the running guide for more details.

MOJO_LISTEN

Can be used to set up listen from an environment variable.

Example:

MOJO_LISTEN="http://127.0.0.1:8080,http://[::1]:8080"

MOJO_REVERSE_PROXY

The MOJO_REVERSE_PROXY environment variable can be used to enable proxy support, this allows Mojolicious to automatically pick up the X-Forwarded-For and X-Forwarded-Proto HTTP headers.

Note that setting this environment variable without a reverse proxy in front will be a security issue.

The FAQ has more details on how to set up Convos behind a reverse proxy server.