Skip to main content

​
Requirements

Docker Engine 24+

Install via curl -fsSL https://get.docker.com | sh

MariaDB 10.6+ or 11.x

An existing external MariaDB instance is required

1 GB RAM minimum

2 GB recommended for production use

4 GB Disk

For the container image and persistent volumes

Soketi (required)

WebSocket server required for the realtime dashboard data feed and provider testing results
Soketi is required, not optional. Without it the dashboard will not receive realtime updates and provider connection tests will not return results to the UI.

​
Installation

Docker run commands assume you already have a database installed and configured. SQLite is fine for most installs, but you can also use more traditional relational databases like MariaDB, MySQL, and PostgreSQL. See Environment Variables for the available DB_CONNECTION drivers and their connection parameters.
1

Prepare your database

Connect to your MariaDB instance and create the database and user:
    CREATE DATABASE zepeed CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'zepeed'@'%' IDENTIFIED BY 'your_strong_password';
    GRANT ALL PRIVILEGES ON zepeed.* TO 'zepeed'@'%';
    FLUSH PRIVILEGES;
Use '%' as the host so the MariaDB user is reachable from inside the Docker container. 'localhost' will not work because the container has its own network namespace.
2

Generate an application key

    echo "base64:$(openssl rand -base64 32 2>/dev/null)"
Copy the full output — it starts with base64:. You will use it as APP_KEY in the next step.
3

Run Soketi (required for realtime features)

Zepeed uses Soketi as its WebSocket server to power the realtime dashboard data feed and to stream provider testing results back to the UI. Start it before launching Zepeed:
    docker run -d \
      --name soketi \
      --restart unless-stopped \
      -p 6001:6001 \
      -e SOKETI_DEFAULT_APP_ID="zepeed" \
      -e SOKETI_DEFAULT_APP_KEY="zepeed_key" \
      -e SOKETI_DEFAULT_APP_SECRET="your_ws_secret" \
      quay.io/soketi/soketi:latest-16-alpine
The SOKETI_DEFAULT_APP_ID, SOKETI_DEFAULT_APP_KEY, and SOKETI_DEFAULT_APP_SECRET values must match the PUSHER_APP_ID, PUSHER_APP_KEY, and PUSHER_APP_SECRET you set on the Zepeed container in the next step.
If Soketi runs on a different host than Zepeed, set PUSHER_HOST to that host’s address (instead of 127.0.0.1) when running the Zepeed container.
4

Run the container

        docker run -d \
          --name zepeed \
          --restart unless-stopped \
          -p 8080:8080 \
          -e APP_KEY="base64:your_generated_key_here" \
          -e APP_URL="http://your-host:8080" \
          -e APP_TIMEZONE="UTC" \
          -e DB_CONNECTION="mariadb" \
          -e DB_HOST="your-mariadb-host" \
          -e DB_PORT="3306" \
          -e DB_DATABASE="zepeed" \
          -e DB_USERNAME="zepeed" \
          -e DB_PASSWORD="your_strong_password" \
          -e PUSHER_APP_ID="zepeed" \
          -e PUSHER_APP_KEY="zepeed_key" \
          -e PUSHER_APP_SECRET="your_ws_secret" \
          -e PUSHER_HOST="127.0.0.1" \
          -e PUSHER_PORT="6001" \
          -e PUSHER_SCHEME="http" \
          -e DEFAULT_ADMIN_NAME="Zepeed Admin" \
          -e DEFAULT_ADMIN_EMAIL="admin@zepeed.local" \
          -e DEFAULT_ADMIN_PASSWORD="your_admin_password" \
          -v zepeed-storage:/var/www/html/storage/app \
          -v zepeed-logs:/var/www/html/storage/logs \
          marjose123/zepeed:latest
See Environment Variables for a full description of every option.
5

Run the container

        docker run -d \
          --name zepeed \
          --restart unless-stopped \
          -p 8080:8080 \
          -e APP_KEY="base64:your_generated_key_here" \
          -e APP_URL="http://your-host:8080" \
          -e APP_TIMEZONE="UTC" \
          -e DB_CONNECTION="mariadb" \
          -e DB_HOST="your-mariadb-host" \
          -e DB_PORT="3306" \
          -e DB_DATABASE="zepeed" \
          -e DB_USERNAME="zepeed" \
          -e DB_PASSWORD="your_strong_password" \
          -e PUSHER_APP_ID="zepeed" \
          -e PUSHER_APP_KEY="zepeed_key" \
          -e PUSHER_APP_SECRET="your_ws_secret" \
          -e PUSHER_HOST="127.0.0.1" \
          -e PUSHER_PORT="6001" \
          -e PUSHER_SCHEME="http" \
          -e DEFAULT_ADMIN_NAME="Zepeed Admin" \
          -e DEFAULT_ADMIN_EMAIL="admin@zepeed.local" \
          -e DEFAULT_ADMIN_PASSWORD="your_admin_password" \
          -v zepeed-storage:/var/www/html/storage/app \
          -v zepeed-logs:/var/www/html/storage/logs \
          marjose123/zepeed:latest
See Environment Variables for a full description of every option.
6

Follow the first-boot logs

    docker logs -f zepeed
Wait until you see: [default-account] Default admin account created: admin@zepeed.localThis confirms that migrations ran successfully and the admin account is ready.
7

Follow the first-boot logs

    docker logs -f zepeed
Wait until you see: [default-account] Default admin account created: admin@zepeed.localThis confirms that migrations ran successfully and the admin account is ready.
8

Open in your browser

Navigate to http://your-host:8080 and log in with the DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD you set in step 3.
Change your password immediately after first login via Profile Settings.
9

Open in your browser

Navigate to http://your-host:8080 and log in with the DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD you set in step 3.
Change your password immediately after first login via Profile Settings.

​
Updating

docker pull marjose123/zepeed:latest
docker stop zepeed && docker rm zepeed
Re-run the same docker run command from step 3. Migrations run automatically on startup. Your volumes (zepeed-storage, zepeed-logs) persist across updates.
To pin a specific version replace :latest with a version tag, e.g. marjose123/zepeed:1.2.0.

​
Useful Commands

docker logs -f zepeed