Skip to content

DOCKER.md

Latest commit

 

History

History
392 lines (280 loc) · 11.5 KB

DOCKER.md

File metadata and controls

392 lines (280 loc) · 11.5 KB
Raw

Docker Deployment Guide for BinktermPHP

This guide covers deploying BinktermPHP using Docker and Docker Compose.

Note: Docker is a best-effort deployment option, not the primary target — the bare-metal install (docs/INSTALL.md) receives the most testing. Docker support is improving as issues are reported; if you run into problems, please report them in the LVLY_BINKTERMPHP echo area or on GitHub.

Table of Contents

Prerequisites

  • Docker Engine 20.10 or newer
  • Docker Compose 2.0 or newer
  • At least 2GB of available RAM
  • 10GB of available disk space

Quick Start

1. Clone the Repository

git clone https://github.com/awehttam/binkterm-php.git
cd binkterm-php

2. Configure Environment Variables

# Copy the example environment file
cp .env.docker.example .env

# Edit the .env file with your settings
nano .env

Important: Change at least these values:

  • DB_PASSWORD - Use a strong password
  • SITE_URL - Your public URL (e.g., https://bbs.example.com)
  • SITE_NAME - Your BBS name
  • SYSOP_NAME - Your name
  • FIDONET_ADDRESS - Your FidoNet address (if applicable)

3. First Run (Initialize Database)

# Set RUN_SETUP=true for first run only
RUN_SETUP=true docker-compose up -d

# Watch the logs to ensure setup completes
docker-compose logs -f binkterm

Wait for the message "Initialization complete!" in the logs.

4. Access Your BBS

Open your browser to http://localhost (or the configured SITE_URL).

The default admin account must be created through the registration page on first use.

Configuration

Environment Variables

Edit the .env file to configure your deployment:

Database Configuration

DB_NAME=binkterm          # Database name
DB_USER=binkterm          # Database username
DB_PASSWORD=changeme      # CHANGE THIS!

Site Configuration

SITE_URL=http://localhost           # Public URL of your BBS
SITE_NAME=BinktermPHP BBS          # Name displayed on your BBS
SYSOP_NAME=Sysop                   # Your name/handle
FIDONET_ADDRESS=1:2/3.4            # Your FidoNet address

Port Mappings

HTTP_PORT=80              # Web interface (default: 80)
BINKP_PORT=24554          # BinkP server (default: 24554)
DOSDOOR_WS_PORT=24555     # DOS Door WebSocket (default: 24555)
BINKSTREAM_WS_PORT=6010   # Realtime (BinkStream) WebSocket (default: 6010)

If you need to use different ports (e.g., 8080 instead of 80):

HTTP_PORT=8080:80         # Map host port 8080 to container port 80

DOS Door Configuration

DOSDOOR_DEBUG_KEEP_FILES=false    # Set to true to keep session files for debugging

Development/Debug

APP_DEBUG=false           # Set to true for verbose error messages

Included Services

docker/supervisord.conf only starts the basic set of services needed for the core web interface and FTN networking. It is not a complete list of everything BinktermPHP can run — several optional daemons documented elsewhere in the project are left out of the Docker image entirely so the default container stays small and focused.

Started automatically

  • apache — the web interface
  • admin_daemon — configuration/management daemon (writes config/*.json on behalf of the web process)
  • realtime_server — BinkStream WebSocket server (live updates in the browser interface)
  • binkp_scheduler — schedules periodic BinkP mail polls
  • binkp_server — FidoNet mail server (BinkP protocol)
  • dosdoor_bridge — DOS door game multiplexing server (Node.js)
  • telnet_daemon — Telnet BBS server

Present but disabled by default

  • gemini_daemon — Gemini protocol server. Present in supervisord.conf with autostart=false; enable it by changing that line to autostart=true and rebuilding, or start it on demand with docker exec -it binkterm-app supervisorctl start gemini_daemon. Also requires publishing GEMINI_PORT in docker-compose.yml.

Not included at all

These daemons exist in the project but have no supervisord.conf entry or exposed port in the default Docker setup:

  • SSH daemon (ssh/ssh_daemon.php, default port 2022) — shares terminal-side code with the Telnet daemon; see ssh/CLAUDE.md
  • MCP server (mcp-server/, default port 3740) — see docs/MCPServer.md
  • Matterbridge daemon (scripts/matterbridge_daemon.php)
  • MRC daemon (scripts/mrc_daemon.php)
  • AI bot daemon (scripts/ai_bot_daemon.php)
  • FTP daemon (scripts/ftp_daemon.php)

If you want to run one of these under Docker, add a [program:...] block for it to docker/supervisord.conf (see Adding Services to Supervisor in docker/README.md for the block format), publish any port it needs in docker-compose.yml and EXPOSE it in the Dockerfile, then rebuild. These are ordinary PHP/Node scripts with no Docker-specific requirements, so wiring one in is the same as adding any other supervisor-managed process.

First Run Setup

Option 1: Environment Variable (Recommended)

RUN_SETUP=true docker-compose up -d

Option 2: Manual Setup

# Start containers
docker-compose up -d

# Run setup manually
docker exec -it binkterm-app php /var/www/html/scripts/setup.php

Important: Only run setup once. After the initial setup, leave RUN_SETUP=false in your .env file.

Managing the Application

Starting the Services

docker-compose up -d

Stopping the Services

docker-compose down

Viewing Logs

# All services
docker-compose logs -f

# Just the BinktermPHP app
docker-compose logs -f binkterm

# Just the database
docker-compose logs -f postgres

Restarting Services

# Restart everything
docker-compose restart

# Restart just the app
docker-compose restart binkterm

Updating the Application

Review version-specific upgrade notes in docs/index.md before upgrading — individual versions may have specific steps you must take.

# Pull latest code
git pull

# Rebuild the image and recreate the container
docker-compose build
docker-compose up -d

# Run any new database migrations
docker exec -it binkterm-app php /var/www/html/scripts/setup.php

docker-compose build followed by up -d is enough to pick up code changes — there's no need to docker-compose down first, since up -d recreates any container whose image changed and leaves the rest running. Use docker-compose build --no-cache instead if a change touched system packages or PHP extensions in the Dockerfile and you want a fully clean rebuild.

scripts/setup.php applies any pending database migrations and is safe to run every time you upgrade, even if there's nothing new to apply. Do not set RUN_SETUP=true for this — that variable is only meant for the very first up -d (see First Run Setup); running setup.php directly like this works against the already-running container without needing to touch .env.

Accessing the Container Shell

docker exec -it binkterm-app bash

Volumes and Data Persistence

Docker Compose creates three persistent volumes:

  • postgres_data - PostgreSQL database files
  • binkterm_data - Application data (logs, packets, uploads, etc.)
  • binkterm_config - Configuration files (bbs.json, webdoors.json, etc.)

Backing Up Data

# Backup database
docker exec binkterm-postgres pg_dump -U binkterm binkterm > backup_$(date +%Y%m%d).sql

# Backup data volume
docker run --rm -v binkterm_data:/data -v $(pwd):/backup alpine tar czf /backup/binkterm_data_$(date +%Y%m%d).tar.gz -C /data .

# Backup config volume
docker run --rm -v binkterm_config:/config -v $(pwd):/backup alpine tar czf /backup/binkterm_config_$(date +%Y%m%d).tar.gz -C /config .

Restoring Data

# Restore database
cat backup.sql | docker exec -i binkterm-postgres psql -U binkterm binkterm

# Restore data volume
docker run --rm -v binkterm_data:/data -v $(pwd):/backup alpine tar xzf /backup/binkterm_data.tar.gz -C /data

# Restore config volume
docker run --rm -v binkterm_config:/config -v $(pwd):/backup alpine tar xzf /backup/binkterm_config.tar.gz -C /config

Troubleshooting

Container Won't Start

Check the logs:

docker-compose logs binkterm

Common issues:

  • Database not ready: Wait for PostgreSQL health check to pass
  • Port already in use: Change HTTP_PORT in .env
  • Permission issues: Ensure data directories are writable

Database Connection Errors

Verify database is running:

docker-compose ps postgres
docker-compose logs postgres

Test database connection:

docker exec -it binkterm-postgres psql -U binkterm -d binkterm

DOS Doors Not Working

Check DOSBox-X installation:

docker exec -it binkterm-app dosbox-x --version

Check DOS door bridge logs:

docker exec -it binkterm-app cat /var/www/html/data/logs/dosdoor_bridge.log

Verify SDL is configured for headless:

docker exec -it binkterm-app printenv | grep SDL
# Should show: SDL_VIDEODRIVER=dummy

Reset Everything (Nuclear Option)

WARNING: This deletes all data!

docker-compose down -v
rm -rf data/ config/
docker-compose up -d

Production Considerations

Security

  1. Change Default Passwords: Always use strong passwords in .env

  2. Use HTTPS: Put a reverse proxy (nginx, Caddy, Traefik) in front of BinktermPHP:

# Example nginx reverse proxy in docker-compose.yml
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - binkterm

  1. Firewall: Only expose necessary ports

    • 80/443 for web access
    • 24554 for BinkP (if accepting FidoNet connections)

  2. Regular Updates: Keep Docker images and BinktermPHP up to date

Performance

  1. Resource Limits: Add resource constraints in docker-compose.yml:
  binkterm:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 512M
  1. PostgreSQL Tuning: Mount custom PostgreSQL config:
  postgres:
    volumes:
      - ./postgresql.conf:/etc/postgresql/postgresql.conf:ro
    command: postgres -c config_file=/etc/postgresql/postgresql.conf

Monitoring

  1. Health Checks: Already configured in docker-compose.yml

  2. Logs: Use log aggregation (e.g., Loki, ELK stack)

  3. Metrics: Consider adding Prometheus exporters

Scaling

For high-traffic deployments:

  • Use external PostgreSQL instance (remove postgres service from compose)
  • Consider load balancing multiple binkterm containers
  • Use shared storage (NFS, S3) for data volumes
  • Separate DOS door bridge to dedicated server

Additional Resources