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/heads/main/docker-compose.prod.sqlite.yml

curl -O https://raw.githubusercontent.com/journiv/journiv-app/refs/heads/main/env.template

curl -o docker-compose.yml https://raw.githubusercontent.com/journiv/journiv-app/refs/heads/main/docker-compose.prod.postgres.yml

curl -O https://raw.githubusercontent.com/journiv/journiv-app/refs/heads/main/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

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.

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.

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:

docker compose logs journiv

Docker Run:

docker 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

Port already in use

Change the host port in your configuration:

Docker Compose:

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

Docker Run:

-p 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:

docker compose exec journiv ls -la /data

Docker Run:

docker exec journiv ls -la /data

Database connection errors

For PostgreSQL setups, verify the following:

Docker Compose:

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

Docker Run:

• Verify DATABASE_URL is correct
• Ensure PostgreSQL is accessible from the container
• Check PostgreSQL logs for connection issues

View logs

Docker Compose:

# All services
docker compose logs

# Specific service
docker compose logs journiv

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

Docker Run:

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

# View last 100 lines
docker logs --tail 100 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.