README.md

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

```bash
# 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

```yaml
# 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

```bash
# 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

```nginx
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:

```yaml
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)

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

### S3-Compatible Storage

```yaml
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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
docker compose -p penpot -f docker-compose.yaml logs -f
```

### Check specific service
```bash
docker compose -p penpot -f docker-compose.yaml logs -f penpot-backend
```

### Database connection issues
```bash
# 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.