Install with Docker Compose

This setup runs MongoDB 6 as a single-node replica set, GearN Server, and GearN Dashboard on one Docker network.

  • Install Docker Engine with the Docker Compose plugin, or Docker Desktop.
  • Allow inbound access to ports 3000, 2202, and 2901 only where required.
  • Use strong, unique secrets before starting the services.
1. Create the deployment directory

Create this structure. The data, log, and upload directories are populated by the containers.

gearn/
├── docker-compose.yml
├── .env
├── GNconfig.json
├── rsfile.key
├── mongo-rs0-1/
│   └── data/db/
└── gearn-server/
    ├── log/
    └── file-upload/

Create GNconfig.json for your environment. See Server Settings for the available configuration groups.

2. Create the environment file

Save the following as .env and replace every placeholder before deployment.

GEARN_VERSION=YOUR_GEARN_VERSION

MONGO_DATABASE_USERNAME=gearn
MONGO_DATABASE_PASSWORD=CHANGE_TO_A_STRONG_PASSWORD
MONGO_DATABASE_NAME=gearn

GEARN_INIT_ROOT_USERNAME=gearnadmin
GEARN_INIT_ROOT_PASSWORD=CHANGE_TO_A_STRONG_ADMIN_PASSWORD
GEARN_INIT_RESTORE_ROOT_PASSWORD=CHANGE_TO_A_STRONG_RECOVERY_PASSWORD
GEARN_TOKEN_PRIVATE_KEY=CHANGE_TO_A_LONG_RANDOM_TOKEN
GEARN_CLUSTER_PRIVATE_KEY=CHANGE_TO_A_DIFFERENT_LONG_RANDOM_TOKEN

GEARN_SERVER_PUBLIC_ADDRESS=http://localhost:2202
3. Create the MongoDB keyfile

The replica set uses this shared secret for internal authentication. Run one command set inside the deployment directory.

Linux or macOS
openssl rand -base64 756 > rsfile.key
chmod 600 rsfile.key
Windows PowerShell
$bytes = New-Object byte[] 756
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
[Convert]::ToBase64String($bytes) | Set-Content -NoNewline rsfile.key
4. Create docker-compose.yml

The health checks initialize MongoDB replica set rs0 and prevent dependent services from starting too early.

services:
  mongo-rs0-1:
    image: mongo:6.0
    hostname: mongo-rs0-1
    restart: always
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGO_DATABASE_USERNAME}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_DATABASE_PASSWORD}
      MONGO_INITDB_DATABASE: ${MONGO_DATABASE_NAME}
    healthcheck:
      test: echo "try { rs.status() } catch(err) { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo-rs0-1:27017',priority:1}]})}" | mongosh --port 27017 -u '${MONGO_DATABASE_USERNAME}' -p '${MONGO_DATABASE_PASSWORD}' --authenticationDatabase admin --quiet
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    volumes:
      - ./mongo-rs0-1/data/db:/data/db
      - ./rsfile.key:/data/rsfile.key
    command: >
      bash -c "
        chown mongodb:mongodb /data/rsfile.key &&
        chmod 600 /data/rsfile.key &&
        exec docker-entrypoint.sh mongod --replSet rs0 --bind_ip_all --keyFile /data/rsfile.key --auth
      "
    networks:
      - gearn-net

  gearn-server:
    image: xmobitea/gearn-server:${GEARN_VERSION}
    hostname: gearn-server
    restart: always
    ports:
      - "2202:2202"
      - "2901:2901"
    depends_on:
      mongo-rs0-1:
        condition: service_healthy
    environment:
      GEARN_SERVER_MONGO_CONNECTION: mongodb://${MONGO_DATABASE_USERNAME}:${MONGO_DATABASE_PASSWORD}@mongo-rs0-1:27017/?authSource=admin&replicaSet=rs0
      GEARN_SERVER_MONGO_DATABASE: ${MONGO_DATABASE_NAME}
      GEARN_SERVER_MONGO_LOG_CONNECTION: mongodb://${MONGO_DATABASE_USERNAME}:${MONGO_DATABASE_PASSWORD}@mongo-rs0-1:27017/?authSource=admin&replicaSet=rs0
      GEARN_SERVER_MONGO_LOG_DATABASE: ${MONGO_DATABASE_NAME}
      GEARN_INIT_ROOT_USERNAME: ${GEARN_INIT_ROOT_USERNAME}
      GEARN_INIT_ROOT_PASSWORD: ${GEARN_INIT_ROOT_PASSWORD}
      GEARN_INIT_RESTORE_ROOT_PASSWORD: ${GEARN_INIT_RESTORE_ROOT_PASSWORD}
      GEARN_TOKEN_PRIVATE_KEY: ${GEARN_TOKEN_PRIVATE_KEY}
      GEARN_CLUSTER_PRIVATE_KEY: ${GEARN_CLUSTER_PRIVATE_KEY}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:2202/ts"]
      interval: 10s
      timeout: 3s
      retries: 5
    volumes:
      - ./GNconfig.json:/app/GNconfig.debug.json
      - ./gearn-server/log:/app/log
      - ./gearn-server/file-upload:/app/file-upload
    networks:
      - gearn-net

  gearn-dashboard:
    image: xmobitea/gearn-dashboard:${GEARN_VERSION}
    hostname: gearn-dashboard
    restart: always
    ports:
      - "3000:3000"
    environment:
      GEARN_SERVER_PUBLIC_ADDRESS: ${GEARN_SERVER_PUBLIC_ADDRESS}
    depends_on:
      gearn-server:
        condition: service_healthy
    networks:
      - gearn-net

networks:
  gearn-net:
5. Start GearN
docker compose config
docker compose pull
docker compose up -d
docker compose ps

Open http://localhost:3000 after all services report healthy.

Check service logs

Run the command for the service you want to inspect. Press Ctrl+C to stop following logs.

docker compose logs -f mongo-rs0-1
docker compose logs -f gearn-server
docker compose logs -f gearn-dashboard
Stop or reset the deployment
docker compose down

# Also delete containers and local MongoDB data:
docker compose down
rm -rf mongo-rs0-1/data/db