Docker Installation

Docker Compose is recommended for production deployments. It provides easy configuration management, allows you to run multiple services together, and simplifies updates and maintenance.

Installation

mkdir journiv
cd journiv

curl -o docker-compose.yml https://raw.githubusercontent.com/journiv/journiv-app/refs/tags/latest/docker-compose.yml

curl -O https://raw.githubusercontent.com/journiv/journiv-app/refs/tags/latest/env.template

curl -o docker-compose.yml https://raw.githubusercontent.com/journiv/journiv-app/refs/tags/latest/docker-compose.sqlite.yml

curl -O https://raw.githubusercontent.com/journiv/journiv-app/refs/tags/latest/env.template

# Using OpenSSL (recommended)
openssl rand -base64 32

# Or using Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

mv env.template .env

SECRET_KEY=your-generated-secret-key-here
DOMAIN_NAME=192.168.1.1
APP_VERSION=latest
DB_DRIVER=postgres
# Preferred: POSTGRES_PASSWORD
POSTGRES_PASSWORD=your-secure-password
# OR: DATABASE_URL with a PostgreSQL URL (postgresql:// or postgres://)
DATABASE_URL=postgresql://user:password@host:5432/dbname
# Do not specify both POSTGRES_PASSWORD and DATABASE_URL. They are mutually exclusive.

SECRET_KEY=your-generated-secret-key-here
DOMAIN_NAME=192.168.1.1
APP_VERSION=latest

docker compose up -d

Required Environment Variables

Two environment variables are required for Journiv to run:

Complete list of environment variables can be found in the Environment Variables section.

Configuration Details

Volume Mounts

The container uses /data as the data directory. Mount this to persist data:

# In docker-compose.yml
services:
  journiv:
    volumes:
      - app_data:/data # Named volume (recommended)
      # OR
      - /path/to/local/data:/data # Bind mount

Data stored in /data:

• Database file (journiv.db for SQLite)
• Media files (media/)
• Logs (logs/)
• Exports (exports/)
• Imports (imports/)

Port Configuration

Change the host port if 8000 is already in use:

# In docker-compose.yml
services:
  journiv:
    ports:
      - "8080:8000" # Use port 8080 on host, 8000 in container

Access Journiv at http://192.168.1.1:8080 instead.

Updating Journiv

To update to the latest version:

# Pull latest images
docker compose pull

# Restart services
docker compose up -d

Important: Always backup your data before updating. Database migrations run automatically on startup.

Backup and Restore

Backup

Full backup (database + media):

# Create backup archive
docker compose exec journiv tar czf /data/backup-$(date +%Y%m%d).tar.gz /data

# Copy backup to host
docker compose cp journiv:/data/backup-YYYYMMDD.tar.gz ./backup.tar.gz

PostgreSQL backup:

# Backup PostgreSQL database
docker compose exec postgres pg_dump -U journiv journiv > backup.sql

Restore

From archive:

# Copy archive to container
docker compose cp ./backup.tar.gz journiv:/data/backup.tar.gz

# Extract archive
docker compose exec journiv tar xzf /data/backup.tar.gz -C /

PostgreSQL restore:

# Restore PostgreSQL database
docker compose exec -T postgres psql -U journiv journiv < backup.sql

Environment Variables

Common environment variables for Docker Compose:

See Environment Variables for complete reference.

Troubleshooting

Container won't start

Check logs to identify the issue:

docker compose logs journiv

Common issues:

• Missing SECRET_KEY or DOMAIN_NAME environment variables
• Port already in use (change host port with -p 8080:8000)
• Permission issues with the /data volume
• "Invalid Host Header": Ensure DOMAIN_NAME or CORS_ORIGINS includes the hostname you are using to access the app.

Port already in use

Change the host port in your docker-compose.yml file:

ports:
  - "8080:8000"  # Use port 8080 instead of 8000

Permission issues

Ensure the data directory is writable:

For bind mounts:

chmod -R 755 /path/to/local/data

For named volumes: Docker handles permissions automatically. If issues persist, check volume access:

docker compose exec journiv ls -la /data

Database connection errors

For PostgreSQL setups, verify the following:

• PostgreSQL container is healthy: docker compose ps
• DATABASE_URL is correct in your configuration
• PostgreSQL credentials match between services

View logs

# All services
docker compose logs

# Specific service
docker compose logs journiv

# Follow logs in real-time
docker compose logs -f journiv

Production Checklist

Before deploying to production:

Essentials:

• Strong SECRET_KEY generated and stored securely
• Strong POSTGRES_PASSWORD (if PostgreSQL is used)
• Set DISABLE_SIGNUP to true to prevent new user registration
• HTTPS configured with reverse proxy

Nice to have:

• Monitoring and alerting set up
• Resource limits configured
• Regular backups plan in place
• Firewall rules configured
• Log rotation configured
• Keep Journiv updated to the latest version

See Configuration for detailed production setup.