Update README.md

README.md

@@ -6,5 +6,252 @@ colorTo: indigo
 sdk: docker
 pinned: false
 ---
+# Penpot Self-Hosting Guide
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## ⚠️ 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.