Create BYCEPS Configuration File

To run BYCEPS, a configuration file is required. It usually resides in config/.

There is an example, config.toml.example, that you can use as a basis for your specific configuration.

Create a copy of the it to adjust as we go along:

$ cp config/config.toml.example config/config.toml

Set a Secret Key

A secret key is, among other things, required for login sessions. So let’s generate one in a cryptographically secure way:

$ uv run byceps generate-secret-key

Exemplary output:

3ac1c416bfacb82918d56720d1c3104fd96e8b8d4fbee42343ae7512a9ced293

Set this value in your configuration file so the line looks like this:

excerpt from config/config.toml
secret_key = "3ac1c416bfacb82918d56720d1c3104fd96e8b8d4fbee42343ae7512a9ced293"

Note: This line has to be in the top part of the configuration file, before any section ([…]).

Attention

Do not use the above key (or any other key you copied from anywhere). Generate your own secret key!

Attention

Do not use the same key for development and production environments. Generate separate secret keys!

Map Applications

Since a single BYCEPS instance can provide the admin frontend, the API, and one or more sites, a mapping (in the [apps] section in the configuration file) is required which defines which hostname will be routed to which application.

  • For a local installation, you can go with the exemplary hostnames already defined in the example configuration file, which are:

    • admin.byceps.example for the admin UI

    • api.byceps.example for the API

    • cozylan.example for the CozyLAN demo site

    To be able to access them, add these entries to your local /etc/hosts file (or whatever the equivalent is for your operating system):

    excerpt from /etc/hosts
    127.0.0.1       admin.byceps.example
127.0.0.1       api.byceps.example
127.0.0.1       cozylan.example

  • But if you are installing to a server on the Internet, substitute above hostnames in the configuration with ones that use actual, registered Internet domains.

Specify SMTP Server

BYCEPS needs to know of an SMTP server, or mail/message transport agent (MTA), to forward outgoing emails to.

The default is to expect a local one on localhost and port 25 without authentication or encryption, like Sendmail or Postfix.

Another option is to use an external one (authentication and encryption are important here!) with a configuration like this:

excerpt from config/config.toml
[smtp]
host = "smtp.provider.example"
port = 465
use_ssl = true
username = "smtp-user"
password = "smtp-password"

See the available SMTP configuration properties.

Set Environment Variable Automatically

The configuration file has to be specified when running most commands. This can be done by prefixing a command with the corresponding environment variable:

$ BYCEPS_CONFIG_FILE=config/config.toml uv run byceps

To avoid doing that everytime, the environment variable can be saved to the .env file in the BYCEPS project path. For example:

$ echo "BYCEPS_CONFIG_FILE=$PWD/config/config.toml" > ./.env

Be sure to use an absolute path so that the file can be found even when running commands from a sub-directory of the BYCEPS project path.