# Docker Deployment Guide > One-click deploy GEO Wiki Pro with Docker, supporting local development and server production environments --- ## 📋 Prerequisites | Requirement | Minimum | |-------------|---------| | Operating System | Linux / macOS / Windows (WSL2) | | Docker | 20.10+ | | Docker Compose | v2.0+ | | Memory | 1GB+ | | Disk Space | 500MB+ | --- ## 🚀 Quick Deployment (3 Steps) ### Step 1: Clone Project ```bash git clone https://github.com/your-org/geo-wiki-pro.git cd geo-wiki-pro ``` ### Step 2: Configure Environment Variables ```bash cp .env.example .env ``` Edit `.env` file to set necessary parameters: ```env # Required: JWT secret (minimum 32 characters) JWT_SECRET=your-super-secret-key-here # Optional configuration PORT=3002 CORS_ORIGINS=http://localhost:3000 RATE_LIMIT_WINDOW_MS=60000 RATE_LIMIT_MAX_REQUESTS=300 ``` ::: warning Make sure to set a strong random `JWT_SECRET`. Do not use default values in production. ::: ### Step 3: Start Service ```bash docker compose up -d ``` Verify service status: ```bash curl http://localhost:3002/api/v1/health ``` Expected output: ```json { "status": "ok", "version": "2.9.0" } ``` --- ## 🏗️ Architecture Overview GEO Wiki Pro adopts a frontend-backend separation architecture: ``` ┌─────────────────┐ ┌─────────────────┐ │ Nginx │────▶│ Express.js │ │ (Static Frontend) │ (API Backend) │ │ Port: 80/443 │ │ Port: 3002 │ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────┐ │ File System │ │ data/ │ │ public/ │ └─────────────┘ ``` ### Service Components | Component | Description | Port | |-----------|-------------|------| | Nginx | Reverse proxy + static file serving | 80/443 | | Express.js | API server | 3002 | | File Storage | Markdown documents + media files | - | --- ## ⚙️ Advanced Configuration ### Custom Port Modify port mapping in `docker-compose.yml`: ```yaml services: api: ports: - "8080:3002" # External port:Internal port ``` ### Mount Data Directory Persist data to host machine: ```yaml services: api: volumes: - ./data:/app/data - ./public/media:/app/public/media ``` ### Configure HTTPS In production environments, it's recommended to use a reverse proxy for HTTPS: ```nginx server { listen 443 ssl; server_name wiki.example.com; ssl_certificate /etc/ssl/certs/wiki.example.com.pem; ssl_certificate_key /etc/ssl/private/wiki.example.com.key; location / { proxy_pass http://localhost:3002; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` --- ## 🔒 Security Configuration ### First Login After deployment, the system automatically creates an admin account: 1. Visit `http://your-server:3002/login` 2. Login with default admin credentials 3. **Immediately change the default password** ### Environment Variable Security | Variable | Description | Security Recommendation | |----------|-------------|------------------------| | `JWT_SECRET` | JWT signing secret | Generate with `openssl rand -base64 32` | | `CORS_ORIGINS` | Allowed CORS origins | Restrict to actual domain in production | | `RATE_LIMIT_*` | Rate limiting config | Adjust based on expected traffic | ::: danger Never commit `.env` files to version control (Git). Ensure `.gitignore` includes `.env`. ::: --- ## 🐛 Common Issues ### Container Fails to Start ```bash # View logs docker compose logs api # Common causes: # 1. .env file not configured with JWT_SECRET # 2. Port already in use # 3. Insufficient Docker permissions ``` ### Data Persistence ```bash # Check data directory ls -la data/ # Backup data tar -czf backup-$(date +%Y%m%d).tar.gz data/ public/media/ ``` ### Update Version ```bash # Pull latest code git pull origin main # Rebuild and start docker compose down docker compose build --no-cache api docker compose up -d ``` --- ## 📊 Monitoring and Maintenance ### Health Check ```bash # API health status curl http://localhost:3002/api/v1/health # Docker container status docker compose ps ``` ### Log Viewing ```bash # Real-time logs docker compose logs -f api # Last 100 lines of logs docker compose logs --tail 100 api ``` --- ## 📚 Next Steps - [Create Your First Knowledge Base](/docs/first-knowledge-base) - Build product knowledge base from scratch - [Quick Start Guide](/docs/quick-start) - Get started with product development in 5 minutes - [FAQ](/docs/faq) - Frequently asked questions --- *Last updated: 2026-05-26 | Version: v2.9.0*