Skip to main content

Docker Installation

Minimum hardware requirements​

  • vCPU: 4 virtual cores (>= 2GHz, more is recommended on larger instances)
  • RAM: 6GB (more is recommended for large instances)
  • Storage: 40GB (more is recommended, especially if you have a lot of remote/local magazines and/or have a lot of (local) users)

You can start with a smaller server and add more resources later if you are using a VPS for example.

System Prerequisites​

  • Docker Engine

  • Docker Compose V2

    If you are using Compose V1, replace docker compose with docker-compose in those commands below.

Docker Install​

The most convenient way to install docker is using an official convenience script provided at get.docker.com:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Alternatively, you can follow the official Docker install documentation for your platform.

Once Docker is installed on your system, it is recommended to create a docker group and add it to your user:

sudo groupadd docker
sudo usermod -aG docker $USER

Mbin Installation​

Preparation​

Clone git repository:

git clone https://github.com/MbinOrg/mbin.git
cd mbin

Environment configuration​

Use either the automatic environment setup script OR manually configure the .env, compose.override.yaml, and OAuth2 keys. Select one of the two options.

tip

Everything configured for your specific instance is in .env, compose.override.yaml, and storage/ (assuming you haven't modified anything else). If you'd like to backup, or even completely reset/delete your instance, then these are the files to do so with.

Automatic setup script​

Run the setup script and pass in a mode (either prod or dev) and your domain (which can be localhost if you plan to just test locally):

./docker/setup.sh prod mbin.domain.tld
note

Once the script has been run, you will not be able to run it again, in order to prevent data loss. You can always edit the .env and compose.override.yaml files manually if you'd like to make changes.

Continue on to the Docker image preparation section for the next steps.

Manually configure .env and compose.override.yaml​

Create config files and storage directories:

cp .env.example_docker .env
touch compose.override.yaml
mkdir -p storage/{caddy_config,caddy_data,media,messenger_logs,oauth,php_logs,postgres,rabbitmq_data,rabbitmq_logs}
  1. Choose your Valkey password, PostgreSQL password, RabbitMQ password, and Mercure password.
  2. Place the passwords in the corresponding variables in .env.
  3. Update the SERVER_NAME, KBIN_DOMAIN and KBIN_STORAGE_URL in .env.
  4. Update APP_SECRET in .env, see the note below to generate one.
  5. Update MBIN_USER in .env to match your user and group id (id -u & id -g).
  6. Optionally: Use a newer PostgreSQL version. Update/set the POSTGRES_VERSION variable in your .env.
note

To generate a random password or secret, use the following command:

tr -dc A-Za-z0-9 < /dev/urandom | head -c 32 && echo
Configure OAuth2 keys​
  1. Create an RSA key pair using OpenSSL:
# If you protect the key with a passphrase, make sure to remember it!
# You will need it later
openssl genrsa -des3 -out ./storage/oauth/private.pem 4096
openssl rsa -in ./storage/oauth/private.pem --outform PEM -pubout -out ./storage/oauth/public.pem
  1. Generate a random hex string for the OAuth2 encryption key:
openssl rand -hex 16
  1. Add the public and private key paths to .env:
OAUTH_PRIVATE_KEY=%kernel.project_dir%/config/oauth2/private.pem
OAUTH_PUBLIC_KEY=%kernel.project_dir%/config/oauth2/public.pem
OAUTH_PASSPHRASE=<Your passphrase from above here>
OAUTH_ENCRYPTION_KEY=<Hex string generated in previous step>

Docker image preparation​

note

If you're using a version of Docker Engine earlier than 23.0, run export DOCKER_BUILDKIT=1, prior to building the image. This does not apply to users running Docker Desktop. More info can be found here

Use the Mbin provided Docker image (default) OR build the docker image locally. Select one of the two options.

The default is to use our prebuilt images from ghcr.io. Reference the next section if you'd like to build the Docker image locally instead.

info

In production a recommended practice is to pin the image tag to a specific release (example: v1.8.2) instead of using latest.

Pinning the docker image version can be done by editing the compose.override.yaml file and uncommenting the following lines (update the version number to one you want to pin to and is available on ghcr.io):

services:
  php:
    image: ghcr.io/mbinorg/mbin:v1.8.2
  messenger:
    image: ghcr.io/mbinorg/mbin:v1.8.2

Build your own image​

If you want to build your own image, add pull_policy: build to both the php and messenger services in compose.override.yaml:

services:
  php:
    pull_policy: build
  messenger:
    pull_policy: build

Once that's done, run docker compose build --no-cache in order to build the Mbin Docker image.

Uploaded media files​

Uploaded media files (e.g. photos uploaded by users) will be stored on the host directory storage/media. They will be served by the web server in the php container as static files.

Make sure KBIN_STORAGE_URL in your .env configuration file is set to be https://yourdomain.tld/media.

You can also serve those media files on another server by mirroring the files at storage/media and changing KBIN_STORAGE_URL correspondingly.

tip

S3 can also be utilized to store images in the cloud. Just fill in the S3_ fields in .env and Mbin will take care of the rest. See this page for more info.

Running behind a reverse proxy​

A reverse proxy is unneeded with this Docker setup, as HTTPS is automatically applied through the built in Caddy server. If you'd like to use a reverse proxy regardless, then you'll need to make a few changes:

  1. In .env, change your SERVER_NAME to ":80":
SERVER_NAME=":80"
  1. In compose.override.yaml, add CADDY_GLOBAL_OPTIONS: auto_https off to your php service environment:
services:
  php:
    environment:
      CADDY_GLOBAL_OPTIONS: auto_https off
  1. Also in compose.override.yaml, add !override to your php ports to override the current configuration and add your own based on what your reverse proxy needs:
services:
  php:
    ports: !override
      - 8080:80

In this example, port 8080 will connect to your Mbin server.

  1. Make sure your reverse proxy correctly sets the common X-Forwarded headers (especially X-Forwarded-Proto). This is needed so that both rate limiting works correctly, but especially so that your server can detect its correct outward facing protocol (HTTP vs HTTPS).
warning

TRUSTED_PROXIES in .env needs to be a valid value (which is the default) in order for your server to work correctly behind a reverse proxy.

tip

In order to verify your server is correctly detecting it's public protocol (HTTP vs HTTPS), visit /.well-known/nodeinfo and look at which protocol is being used in the href fields. A public server should always be using HTTPS and not contain port numbers (i.e., https://DOMAINHERE/).

Running the containers​

By default docker compose will execute the compose.yaml and compose.override.yaml files.

Run the container in the background (-d means detach, but this can also be omitted for testing or debugging purposes):

docker compose up -d

See your running containers via: docker ps.

This docker setup comes with automatic HTTPS support. Assuming you have set up your DNS and firewall (allow ports 80 & 443) configured correctly, then you should be able to access the new instance via your domain.

note

If you specified localhost as your domain, then a self signed HTTPS certificate is provided and you should be able to access your instance here: https://localhost.

You can also access the RabbitMQ management UI via http://localhost:15672.

warning

Be sure not to forget the Mbin first setup instructions in order to create your admin user, random magazine, and AP & Push Notification keys.