Documentation

Self-hosting

Redbrix running on your own server, with Docker. It reaches the databases on your own network, and nothing about them leaves it. You need Docker with Docker Compose, and about 1 GB of memory for Redbrix and its own database.

Installing

Every way of installing ends at Redbrix's setup screen, where you enter a setup code and your licence key, and create the administrator account. The key comes from your Customer Portal. New to Redbrix? Create an account and start your free 30-day trial there when the setup screen asks for the key, so none of the 30 days is spent installing.

In one command

On a Linux server, macOS, or Windows in Git Bash or WSL (see on your own computer):

curl -fsSL https://app.redbrix.io/self-hosted/install.sh | sh

It asks whether to use HTTPS, the port and the address people will use, makes a redbrix folder with new keys generated on the server, starts Redbrix, and prints the setup code and the address to open. Read the script first if you like; it is short. It changes nothing outside that folder and sends nothing anywhere.

With the files from your Customer Portal

For when you can't run the installer: on Windows without Git Bash or WSL, or where policy does not allow running scripts. On the Self-hosted page of your Customer Portal, choose Can't run the script?, choose whether to use HTTPS, enter the address and port, and choose Download install files. The zip holds the instructions, docker-compose.yml and a ready-filled .env whose keys were made in your browser and never sent to us. Copy the redbrix folder to the server, then, in it:

docker compose up -d
docker compose logs redbrix

The setup code is near the end of the log. Open the address in a browser.

On your own computer, to try it

With Docker Desktop, run the one-line installer: on macOS in Terminal, and on Windows in Git Bash (which comes with Git for Windows) or WSL, not in PowerShell. Choose none for HTTPS and give the address as http://localhost:8080. You do not need HTTPS for this: browsers treat localhost as secure, and nothing leaves the machine.

On Windows with neither Git Bash nor WSL, download the install files from your Customer Portal instead, with the same address, unzip them, and run docker compose up -d in the redbrix folder.

In a WSL Linux distribution such as Ubuntu, with Docker installed there, the installer works as on any Linux server. To reach a database running on Windows itself, see databases on the same machine.

By hand

  1. Put docker-compose.yml and redbrix.env.example in a folder of their own, and copy redbrix.env.example to .env there.
  2. Generate two keys by running this twice, and put the first in APP_KEY and the second in CREDENTIAL_KEY:
    docker run --rm ghcr.io/redbrix-io/redbrix php artisan key:generate --show
    Keep a copy of both somewhere safe. Saved database passwords are encrypted with CREDENTIAL_KEY; without it they cannot be read, by you or by us.
  3. Set DB_PASSWORD to a long random password, and APP_URL to the address people will type to reach Redbrix, such as http://redbrix.internal:8080.
  4. Start it with docker compose up -d, and find the setup code near the end of docker compose logs redbrix.
  5. Open APP_URL in a browser, enter the setup code and your licence key, and create the administrator account. Invite everyone else from Members.

Your licence

The Licence page, for administrators, shows who Redbrix is licensed to, how many people it covers, and when it ends. Redbrix checks the key on your server and never contacts us.

  • In the 30 days before the end date, everyone sees a notice.
  • For 30 days after it, everything keeps working while you renew.
  • After that Redbrix is read-only, for as long as you like: people can sign in, view and export, but not change data. Your data is never deleted or locked away.

To renew, or to cover more people, paste the new key on the Licence page. It takes effect at once. To keep the key in configuration instead, set REDBRIX_LICENCE_KEY in .env, and restart Redbrix after changing it.

Buying and renewing

A licence covers a number of users for a year, and is bought from the Self-hosted page of your Customer Portal by the account's owner. Prices are on the pricing page; for more than 50 users, get in touch.

Ordering

Choose the number of users, and give the company name, the address for the invoice, the email address it should go to, and, if you have them, a VAT number and a purchase order number. We email an invoice straight away, payable within 30 days by bank transfer or card, from the link in the email. VAT is added where it applies.

You don't have to wait for the payment to go through: a key valid for 45 days is ready in the portal as soon as you order, so you can install Redbrix, or carry on after a trial, at once. When the invoice is paid, the key for the full year follows by email, to the invoice address and the account's administrators, and appears in the portal. The year runs from the day you ordered. Paste the new key on the Licence page in Redbrix.

Renewing

  • 60 days before the end of the year, we email to say the licence will renew, for how many users and at what price.
  • 30 days before the end, we email the invoice for the next year. When it is paid, the next year's key follows, as before.

Changing your licence

From the Self-hosted page of your Customer Portal, the owner can:

  • Add users now. Choose a larger number of users and pay the difference for the rest of the year. The key for the larger number follows when that invoice is paid, and the licence renews at the larger number.
  • Change the number of users for next year, up or down. Fewer users take effect from the next year.
  • Stop the licence renewing. It runs to the end of the year you have paid for. Changed your mind? Undo it from the same page.

Changes to the renewal, including stopping it or undoing that, can be made until 30 days before the end of the year, when the next invoice is raised. After that, get in touch.

Databases on the same machine

Inside Redbrix's container, localhost and 127.0.0.1 mean the container itself, not the machine it runs on. For a database on the same machine as Redbrix, use the host name host.docker.internal, with the database's usual port. This works on Linux servers as well as with Docker Desktop on Windows and macOS. If you type localhost, Redbrix says so and offers to put host.docker.internal in for you.

Windows, with Docker installed inside WSL. If you installed Docker Engine inside a WSL Linux distribution, rather than Docker Desktop, host.docker.internal is that Linux system, not Windows. For a database running on Windows, use Windows's address as that Linux system sees it, which this command shows there:

ip route show default | awk '{print $3}'

It is usually something like 172.30.0.1, and can change when Windows restarts. The installer prints it at the end.

Databases elsewhere on your network are reached by their usual name or address.

If a connection is refused

  • "Access denied", or "Host … is not allowed to connect", for a user that works elsewhere. The database server sees Redbrix's connection coming from a Docker network address, not from localhost, so a user such as 'root'@'localhost' is refused. Use a user allowed to connect from other hosts, for example 'redbrix'@'%', with access to the databases people need. Each database server has its own users: a MySQL and a MariaDB on the same machine each need one.
  • "Nothing answered" at the right address. The database server may be listening only on 127.0.0.1. Check bind-address for MySQL and MariaDB, or listen_addresses for PostgreSQL, and that a firewall allows the port.
  • The port is already in use. Redbrix listens on port 8080. Set REDBRIX_PORT in .env to a free port, change the port in APP_URL to match, and run docker compose up -d again.

HTTPS

Both the installer and the Customer Portal can put Caddy, a widely used open-source web server, in front of Redbrix to serve it over HTTPS. There are two ways:

  • Automatic certificate. Caddy gets a free certificate from Let's Encrypt and renews it itself. The server needs a public name, such as redbrix.example.com, with ports 80 and 443 reachable from the internet.
  • Your own certificate. For a server on an internal network, use a certificate from your organisation's certificate authority. The installer asks for its files; with the download, put them in the certs folder as redbrix.crt and redbrix.key.

Plain HTTP is redirected to HTTPS, and Redbrix's own port is reachable from the server itself only, so nobody can go round HTTPS. If you already run a reverse proxy or load balancer, point it at Redbrix's port instead, and set APP_URL to the https:// address, TRUSTED_PROXIES to the proxy's address, and SESSION_SECURE_COOKIE=true.

Email

Without a mail server, Redbrix shows each invitation as a link for you to send, and forgotten passwords are reset from the command line:

docker compose exec redbrix php artisan redbrix:reset-password someone@example.com

To have Redbrix send invitations and password resets itself, set the MAIL_ settings in .env.

Versions and upgrading

Each release has a version number, such as 1.4.0. docker-compose.yml follows every new release (latest). To decide for yourself when to move to a new version, set REDBRIX_IMAGE in .env to ghcr.io/redbrix-io/redbrix:1.4, which follows only the fixes to 1.4. The Licence page shows which version is running. We support releases up to 12 months old.

To upgrade, back up first (below), then:

docker compose pull
docker compose up -d

Redbrix updates its own database as it starts. Going back to an earlier version is not supported: restore the backup you made before upgrading instead.

Backups

Back up two things, together:

  • Redbrix's own database: accounts, saved connections and settings.
  • Your .env file, with its keys. A backup restored without the same CREDENTIAL_KEY cannot read the passwords saved in it.
docker compose exec mariadb sh -c 'mariadb-dump --single-transaction -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > redbrix-backup.sql

To restore into a fresh install, start it with your .env, then:

docker compose exec -T mariadb sh -c 'mariadb -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' < redbrix-backup.sql
docker compose restart redbrix

Redbrix does not store your own databases; back them up as you do now.

Starting again

docker compose down stops Redbrix and keeps its data. To remove an install completely, including all of Redbrix's own data, run docker compose down --volumes in its folder. Deleting the folder alone leaves the data behind, in a Docker volume named after the folder, such as redbrix_redbrix-data; remove it with docker volume rm. Your own databases are not affected either way.

Getting help

redbrix:doctor checks the installation: the database, the keys, the licence, email, storage, and whether any of Redbrix's files have been changed.

docker compose exec redbrix php artisan redbrix:doctor

Its output is a support report. It holds no data, passwords, keys or host names, so you can send it as it is to support@redbrix.io. Redbrix is licensed under the Redbrix Self-Hosted Software Licence.