Installation (Docker Compose)¶

As an alternative to installing directly on a system, BYCEPS can be run from Docker containers, orchestrated by Docker compose.

Important

This guide assumes you are using Docker Compose V2. If you are still using V1, replace docker compose with docker-compose before running commands that include it.

Since there is no official Docker image for BYCEPS at this point, you have to build one yourself.

Obtain BYCEPS¶

First, clone BYCEPS’ Git repository to your machine:

$ git clone https://github.com/byceps/byceps.git

A new directory, byceps, should have been created. cd into it.

Docker Preparation¶

Both a Dockerfile (to build a Docker image) and a compose.yml (to run containers with Docker Compose) come with BYCEPS.

Create the services (build images, create volumes, etc.). This might take a few minutes.

$ docker compose up --no-start

Secret Key¶

Then generate a secret key and put it in a file Docker Compose is configured to pick up as a secret:

$ docker compose run --rm byceps-apps byceps generate-secret-key > ./secret_key.txt

Database¶

Now create and initially populate the relational database structure:

$ docker compose run --rm byceps-apps byceps initialize-database

Initial User¶

With the tables and the authorization data in place, create the initial user (which will get all available roles assigned):

$ docker compose run --rm byceps-apps byceps create-superuser
Screen name: Flynn
Email address: flynn@flynns-arcade.net
Password:
Creating user "Flynn" ... done.
Enabling user "Flynn" ... done.
Assigning 35 roles to user "Flynn" ... done.

Hostname-to-Application Routing¶

Since a single BYCEPS instance can provide the admin frontend, the API, and one or more sites, a configuration file is required that defines which hostname will be routed to which application.

Copy the included example configuration file:

$ cp config/apps_example.toml config/apps.toml

For a local installation, you can go with the examplary hostnames already defined in the example apps configuration file, config/apps_example.toml, 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, though, add these entries to your local /etc/hosts file (or whatever the equivalent of your operating system is):
```
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, substitude above hostnames in the config with ones that use actual, registered Internet domains.

Start BYCEPS¶

With that configured, spin up the application:

$ docker compose up

The admin frontend should now be available at http://admin.byceps.example:8080/. Log in with the name of the initial user you created before and the corresponding password.

The “CozyLAN” party site should be accessible at http://cozylan.example:8080/. (If you logged in to the admin frontend just before, you might be logged in already as the same user.)

Attention

For security reasons, BYCEPS only sends cookies back after login over an HTTPS-secured connection by default.

It is expected that BYCEPS is run behind a reverse proxy that adds TLS termination (e.g. nginx or Caddy; often with a certificate from Let’s Encrypt).

To be able to login without HTTPS using above links, you can temporarily disable session cookie security by setting SESSION_COOKIE_SECURE to false: In compose.yaml add SESSION_COOKIE_SECURE: false on a separate, indented line to the section x-byceps-base-env.