froxlor Container

This repository provides the official froxlor container image for Docker, Kubernetes, and other container platforms.

Note

This container image is currently in development and is not yet recommended for production use. It contains the latest development version of froxlor.

If you want to install froxlor directly on a bare-metal or virtual server, without a container platform, use the main froxlor repository.

Quick Start

The following example starts a minimal froxlor container using Docker Compose.

Tip

Check the developer guide for information on setting up a development environment.

Single Node Installation

Start by creating a fresh froxlor directory for your configuration files.

mkdir froxlor
cd froxlor

wget https://raw.githubusercontent.com/froxlor/froxlor/refs/heads/main/.env.example -O .env

Setup DB_* environment variables to match with the compose.yml db service. Example:

DB_CONNECTION=mariadb
DB_HOST=db
DB_PORT=3306
DB_DATABASE=froxlor
DB_USERNAME=froxlor
DB_PASSWORD=CHANGEM3

Create a compose.yml file:

services:
    froxlor:
        image: hub.froxlor.io/froxlor/froxlor:latest
        restart: unless-stopped
        # options grant the container elevated host access
        # and is required to use the host as local node
        privileged: true
        pid: "host"
        # Use the environment and/or the env_file as you like
        environment:
            FROXLOR_HTTPS: true
        env_file: .env
        # These ports are used for the froxlor ui
        ports:
            - "8000:8000" # HTTP
            - "8443:8443" # HTTPS
        volumes:
            - froxlor:/var/www/html/froxlor
    db:
        image: mariadb:latest
        restart: unless-stopped
        environment:
            MARIADB_ROOT_PASSWORD: CHANGEM3
            MARIADB_DATABASE: froxlor
            MARIADB_USER: froxlor
            MARIADB_PASSWORD: CHANGEM3
        healthcheck:
            test: [ "CMD", "healthcheck.sh", "--connect", "--innodb_initialized" ]
            start_period: 30s
            interval: 10s
            timeout: 5s
            retries: 5
        volumes:
            - database:/var/lib/mysql
volumes:
    froxlor:
    database:

Start the container:

docker compose up -d

Open froxlor in your browser:

https://<your-server-ip>:8443

Database Privileges

Mail and FTP nodes look up domains, mailboxes and FTP accounts directly in the froxlor database (like froxlor v2). froxlor creates a read-only database user per node that may only read the views of that node. For this, the froxlor database user needs CREATE USER and GRANT OPTION:

GRANT CREATE USER ON *.* TO 'froxlor'@'%';
GRANT ALL PRIVILEGES ON `froxlor`.* TO 'froxlor'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Without these privileges, run php artisan mail:node-access <node> or php artisan ftp:node-access <node> and execute the printed statements as database administrator.

The nodes connect to the database over the network: the database has to be reachable from them (node settings mail.lookup_db_host/access.lookup_db_host if they see it under another address). For remote nodes, enable TLS for these connections (mail.lookup_db_tls, access.lookup_db_tls) and restrict the host the lookup users may connect from (mail.lookup_user_host, access.lookup_user_host).

Running Without Privileged Host Access

Some froxlor features require elevated host access. Running the container without privileged and pid: "host" may disable functionality that depends on local node management.

To run the container without privileged host access, remove these lines from your compose.yml:

privileged: true
pid: "host"

Consequences

When privileged host access is disabled:

• Local node management will be disabled.
• Features that require direct host-level access may not work.
• To continue managing services remotely, install and configure the froxlor Remote Adapter package.

Production Recommendations

For production deployments, consider the following recommendations:

• Use persistent volumes Store froxlor data outside the container to prevent data loss during container recreation.

• Use a reverse proxy Place froxlor behind a reverse proxy such as Caddy, Nginx, or Traefik.

• Enable HTTPS Secure all browser-to-panel communication with TLS.

• Pin image versions Avoid using the latest tag in production. Use a specific image version once stable tags are available.

• Review privileged access Only run the container with privileged host access when your deployment explicitly requires it.

License

This project is licensed under the GNU Lesser General Public License, version 3 or (at your option) any later version, with the froxlor Extension Package Exception (SPDX: LGPL-3.0-or-later WITH LicenseRef-froxlor-Extension-Package-Exception).

• COPYING.LESSER: GNU Lesser General Public License, version 3
• COPYING: GNU General Public License, version 3 (incorporated by the LGPL)
• LICENSE-EXCEPTION: froxlor Extension Package Exception
• AUTHORS: the copyright holders

The license of each file is stated in its header or in REUSE.toml (REUSE layout, license texts in LICENSES/).