README.md

metadata

title: Penpot
emoji: 😻
colorFrom: yellow
colorTo: indigo
sdk: docker
pinned: false

Penpot Self-Hosting Guide

⚠️ IMPORTANT: Hugging Face Spaces Limitations

Hugging Face Spaces is NOT recommended for hosting Penpot because:

1. No Docker-in-Docker support - Spaces doesn't support running Docker containers inside containers
2. Multi-container limitations - Penpot requires 5+ services (frontend, backend, exporter, PostgreSQL, Valkey/Redis)
3. Resource constraints - Free Spaces have limited CPU, RAM, and storage
4. Persistence issues - Spaces may reset storage, losing user data
5. Networking complexity - Inter-service communication is challenging

Recommended Deployment Methods

1. Official Docker Compose (Recommended)

For self-hosting on your own server or VPS:

# Download docker-compose.yaml
wget https://raw.githubusercontent.com/penpot/penpot/main/docker/images/docker-compose.yaml

# Generate a secure secret key
python3 -c "import secrets; print(secrets.token_urlsafe(64))"

# Edit docker-compose.yaml and update:
# - PENPOT_SECRET_KEY with the generated key
# - PENPOT_PUBLIC_URI with your domain (e.g., https://penpot.yourdomain.com)
# - Remove 'disable-secure-session-cookies' and 'disable-email-verification' flags for production

# Start Penpot
docker compose -p penpot -f docker-compose.yaml up -d

# Access Penpot at http://localhost:9001

2. Elestio (One-Click Hosting)

Elestio provides managed Penpot hosting with:

• Automatic updates
• SSL certificates
• Backups
• Monitoring

Visit: https://elest.io/open-source/penpot

3. Official SaaS

Use the official hosted version at: https://design.penpot.app

Docker Compose Configuration

The included docker-compose.yaml file contains 6 services:

1. penpot-frontend - Web interface (port 9001)
2. penpot-backend - API server
3. penpot-exporter - Export/rendering service
4. penpot-postgres - Database
5. penpot-valkey - Cache/WebSocket notifications
6. penpot-mailcatch - Email testing (port 1080)

Key Configuration Options

# Security (REQUIRED for production)
PENPOT_SECRET_KEY: "your-random-512-bit-key-here"
PENPOT_PUBLIC_URI: "https://penpot.yourdomain.com"

# Flags (adjust for production)
PENPOT_FLAGS: |
  enable-smtp
  enable-prepl-server
  login-with-password
  registration
  
  # Remove these for production:
  # disable-email-verification
  # disable-secure-session-cookies

Creating Admin Users

# Create a new user (when registration is disabled)
docker exec -ti penpot-penpot-backend-1 python3 manage.py create-profile

# Skip onboarding
docker exec -ti penpot-penpot-backend-1 python3 manage.py create-profile --skip-tutorial --skip-walkthrough

HTTPS Setup (Required for Production)

Example NGINX Configuration

server {
  listen 443 ssl;
  server_name penpot.yourdomain.com;

  client_max_body_size 31457280;

  ssl_certificate /path/to/fullchain.pem;
  ssl_certificate_key /path/to/privkey.pem;

  # WebSockets
  location /ws/notifications {
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_pass http://localhost:9001/ws/notifications;
  }

  # Proxy pass
  location / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Scheme $scheme;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://localhost:9001/;
  }
}

Email Configuration (Production)

Replace the mailcatch service with real SMTP settings:

PENPOT_SMTP_DEFAULT_FROM: noreply@yourdomain.com
PENPOT_SMTP_DEFAULT_REPLY_TO: support@yourdomain.com
PENPOT_SMTP_HOST: smtp.yourmailprovider.com
PENPOT_SMTP_PORT: 587
PENPOT_SMTP_USERNAME: your-username
PENPOT_SMTP_PASSWORD: your-password
PENPOT_SMTP_TLS: true
PENPOT_SMTP_SSL: false

Storage Options

Local Filesystem (Default)

PENPOT_ASSETS_STORAGE_BACKEND: assets-fs
PENPOT_STORAGE_ASSETS_FS_DIRECTORY: /opt/data/assets

S3-Compatible Storage

PENPOT_ASSETS_STORAGE_BACKEND: assets-s3
PENPOT_STORAGE_ASSETS_S3_ENDPOINT: https://s3.amazonaws.com
PENPOT_STORAGE_ASSETS_S3_BUCKET: your-bucket-name
AWS_ACCESS_KEY_ID: your-access-key
AWS_SECRET_ACCESS_KEY: your-secret-key

Backup and Restore

Backup Volumes

# Backup PostgreSQL data
docker run --rm -v penpot_postgres_v15:/data -v $(pwd):/backup ubuntu tar czf /backup/postgres-backup.tar.gz /data

# Backup assets
docker run --rm -v penpot_assets:/data -v $(pwd):/backup ubuntu tar czf /backup/assets-backup.tar.gz /data

Restore Volumes

# Restore PostgreSQL
docker run --rm -v penpot_postgres_v15:/data -v $(pwd):/backup ubuntu tar xzf /backup/postgres-backup.tar.gz -C /

# Restore assets
docker run --rm -v penpot_assets:/data -v $(pwd):/backup ubuntu tar xzf /backup/assets-backup.tar.gz -C /

Updating Penpot

# Pull latest images
docker compose -f docker-compose.yaml pull

# Restart with new images
docker compose -p penpot -f docker-compose.yaml up -d

Important: Update incrementally (e.g., 2.0 → 2.1 → 2.2) rather than jumping versions.

System Requirements

Minimum

• 2 CPU cores
• 4 GB RAM
• 20 GB storage
• Docker 20.10+
• Docker Compose 2.0+

Recommended

• 4 CPU cores
• 8 GB RAM
• 50+ GB storage (depends on usage)

Troubleshooting

Check logs

docker compose -p penpot -f docker-compose.yaml logs -f

Check specific service

docker compose -p penpot -f docker-compose.yaml logs -f penpot-backend

Database connection issues

# Check PostgreSQL is healthy
docker exec penpot-penpot-postgres-1 pg_isready -U penpot

Access mailcatch (for testing emails)

Visit: http://localhost:1080

Security Checklist for Production

• Generate and set a secure PENPOT_SECRET_KEY
• Remove disable-email-verification flag
• Remove disable-secure-session-cookies flag
• Set up HTTPS with valid SSL certificates
• Configure real SMTP server (not mailcatch)
• Change default PostgreSQL password
• Set up regular backups
• Configure firewall rules
• Enable only necessary authentication methods
• Set up monitoring and logging

Additional Resources

• Official Documentation: https://help.penpot.app/technical-guide/
• Configuration Guide: https://help.penpot.app/technical-guide/configuration/
• Community Forum: https://community.penpot.app/
• GitHub Repository: https://github.com/penpot/penpot

License

Penpot is open source software licensed under the Mozilla Public License Version 2.0.