hexo-deploy/README.md

Hexo Blog Docker Containerization Solution

Project Status: ✅ Production Ready | Latest Version: v0.0.3 (Stable) | Updated: May 30, 2025

An enterprise-grade Hexo blog Docker containerization solution providing SSH access, Nginx web service, Git auto-deployment, and comprehensive security protection. Version v0.0.3 is a stable version focusing on core feature reliability and ease of use.

📖 Quick Start: 30-Second Deployment Guide
📖 Complete Guide: Detailed Deployment Documentation
📖 Chinese Documentation: README_zh.md
📋 Version History: Comprehensive Version Summary

🚀 Quick Start

Instant Deployment (30 seconds)

# Build and start stable version
docker build -f Dockerfile_v0.0.3 -t hexo-blog:stable . && `
docker run -d --name hexo-blog-stable --restart unless-stopped -p 8080:80 -p 2222:22 hexo-blog:stable && `
Write-Host "🎉 Deployment Complete! Visit: http://localhost:8080" -ForegroundColor Green

Access Verification

• 🌐 Web Interface: http://localhost:8080
• 💚 Health Check: http://localhost:8080/health
• 📊 Container Status: docker ps | findstr hexo-blog

✨ Core Features

v0.0.3 Stable Features ✅

• 🛡️ SSH Key Authentication - Secure remote access and deployment
• 🌐 Nginx Web Service - High-performance static file serving
• 🔄 Git Auto Deployment - Push-to-update automation workflow
• 💚 Health Monitoring - /health endpoint real-time status monitoring
• 🐳 Docker Optimized - Streamlined image, fast startup
• 📝 Smart Log Management - Including log rotation and size control.

📚 Complete Documentation Index

Document Type	File Link	Purpose	Status
Quick Deploy	README_QUICK_START_SIMPLE.md	30-second deployment	✅
Complete Guide	README_QUICK_START_COMPLETE.md	Detailed configuration and troubleshooting	✅
Version Summary	doc/COMPREHENSIVE_VERSION_SUMMARY.md	Complete version history and comparison	✅
Production Deploy	doc/summary/v0.0.3/	v0.0.3 production environment deployment	✅
Test Guide	test/v0.0.3/windows/README.md	v0.0.3 testing and verification	✅

🧪 Testing and Verification

Automated Testing (v0.0.3)

# v0.0.3 stable version comprehensive testing
cd "test\v0.0.3\windows"
.\run_test.ps1
.\functional_test.ps1
.\log_rotation_test.ps1
.\cleanup_test.ps1

# Testing includes:
# ✅ Container health check
# ✅ Web service functionality      
# ✅ SSH key authentication
# ✅ Git deployment workflow  
# ✅ Log rotation mechanism

Manual Verification

# v0.0.3 stable version verification
docker ps | findstr hexo-blog                    # Container status
curl http://localhost:8080/health                # Health check
ssh -i .\ssh-keys\your_private_key_file -p 2222 hexo@localhost # SSH connection (use your key file)
git push docker main                             # Git deployment
# Check deployment log
docker exec hexo-blog-stable cat /var/log/container/deployment.log

🔧 Environment Variables Configuration

SSH Configuration

• SSH_PORT - SSH port (default: 22)
• PERMIT_ROOT_LOGIN - Allow root login (default: no)
• PUID - hexo user ID (default: 1000)
• PGID - hexo group ID (default: 1000)

Nginx Configuration

• HTTP_PORT - HTTP port (default: 80)
• NGINX_USER - Nginx worker process user (default: hexo)
• NGINX_WORKERS - Number of worker processes (default: auto)
• NGINX_CONNECTIONS - Worker connections (default: 1024)
• SERVER_NAME - Server name (default: localhost)
• WEB_ROOT - Web root directory (default: /home/www/hexo)

System Configuration

• TZ - Timezone (default: Asia/Shanghai)

📦 Deployment Guide

Build Images

# v0.0.3 stable version build  
docker build -f Dockerfile_v0.0.3 -t hexo-blog:v0.0.3 .

# Custom build arguments
docker build -f Dockerfile_v0.0.3 -t hexo-blog:v0.0.3 `
  --build-arg PUID=1001 `
  --build-arg PGID=1001 `
  --build-arg TZ=Asia/Shanghai `
  .

# View detailed build process
docker build -f Dockerfile_v0.0.3 -t hexo-blog:v0.0.3 --progress=plain .

Basic Deployment

# v0.0.3 stable version - simple deployment
docker run -d `
  --name hexo-blog-stable `
  -p 2222:22 `
  -p 8080:80 `
  -v ${PWD}\hexo-data:/home/www/hexo `
  -v ${PWD}\ssh-keys:/home/hexo/.ssh `
  -v ${PWD}\container-logs:/var/log/container `
  hexo-blog:v0.0.3

Production Environment Deployment

# v0.0.3 stable version - production configuration
docker run -d `
  --name hexo-blog-prod `
  --restart unless-stopped `
  -p 2222:22 `
  -p 8080:80 `
  -e SSH_PORT=22 `
  -e HTTP_PORT=80 `
  -e PUID=1001 `
  -e PGID=1001 `
  -e SERVER_NAME=yourdomain.com `
  -e NGINX_WORKERS=auto `
  -e NGINX_CONNECTIONS=1024 `
  -v ${PWD}\hexo-data:/home/www/hexo `
  -v ${PWD}\ssh-keys:/home/hexo/.ssh `
  -v ${PWD}\container-logs:/var/log/container `
  -v ${PWD}\nginx-logs:/var/log/nginx `
  hexo-blog:v0.0.3

Docker Compose Deployment

version: '3.8'
services:
  hexo-blog:
    build:
      context: .
      dockerfile: Dockerfile_v0.0.3
      args:
        - PUID=1001
        - PGID=1001
        - TZ=Asia/Shanghai
    container_name: hexo-blog-stable
    restart: unless-stopped
    ports:
      - "2222:22"
      - "8080:80"
    environment:
      - PUID=1001
      - PGID=1001
      - SERVER_NAME=yourdomain.com
      - NGINX_WORKERS=auto
      - NGINX_CONNECTIONS=1024
      - TZ=Asia/Shanghai
    volumes:
      - ./hexo-data:/home/www/hexo
      - ./ssh-keys:/home/hexo/.ssh
      - ./git-repo:/home/hexo/hexo.git
      - ./logs/container:/var/log/container
      - ./logs/nginx:/var/log/nginx
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

🛡️ Security Features

v0.0.3 Security Features

• ✅ SSH Password Authentication Disabled - Key-based authentication only
• ✅ Root Login Disabled - Principle of least privilege
• ✅ Nginx Non-root Execution - hexo user privilege isolation
• ✅ Security Response Headers - CSP, X-Frame-Options, X-Content-Type-Options
• ✅ Server Identity Hidden - Reduced information disclosure
• ✅ Dynamic PUID/PGID - File permission security

⚡ Performance Optimization

v0.0.3 Performance Features

• 🚀 Gzip Compression - Smart compression for text files
• 🚀 Static File Caching - Reasonable cache header settings
• 🚀 Nginx Performance Tuning - sendfile, tcp_nopush, tcp_nodelay
• 🚀 Multi-stage Build - Reduced image size

📊 Monitoring & Logging

v0.0.3 Monitoring & Logging Features

• 📊 Health Check - /health endpoint, 30-second interval checks
• 📝 Smart Log Management - Colored output, 10MB size limit rotation, keeps last 5 log files.
• 📊 Service Monitoring - Basic process status monitoring, auto-restart
• 🔍 Enhanced startup logs: Detailed container startup process, configuration validation, and dynamic permission application
• 🔄 Periodic log rotation: Automatic log file rotation checks every 30 minutes with timestamped backups

Git Deployment

The container includes a bare Git repository for easy deployment:

# On your local machine, add the container as a remote
# Replace your-server with your server's IP or hostname, and 2222 with the mapped SSH port
git remote add deploy ssh://hexo@your-server:2222/home/hexo/hexo.git

# Deploy your Hexo site (ensure your SSH key is added to the agent or specified)
git push deploy main

The post-receive hook will automatically checkout files to /home/www/hexo, set proper permissions, and log detailed deployment information including file counts and total size to /var/log/container/deployment.log.

Volumes

Volume Path in Container	Description	Purpose
/home/www/hexo	Hexo site files	Static website content
/home/hexo/.ssh	SSH keys and configuration	SSH authentication (mount your authorized_keys)
/home/hexo/hexo.git	Git repository for deployment	Automated deployment (managed by container)
/var/log/container	Container service logs	Application logging (e.g., deployment.log)
/var/log/nginx	Nginx access and error logs	Web server logging

Port Mapping

Container Port	Host Port (Example)	Protocol	Description
22	2222	TCP	SSH server
80	8080	TCP	HTTP web server

Troubleshooting

Container won't start

# Check container logs
docker logs hexo-blog-stable # Or your container name

# Check health status
docker inspect hexo-blog-stable | Select-String Health -A 10

# Check for port conflicts on the host
netstat -an | findstr "8080" # Check for your HTTP port
netstat -an | findstr "2222" # Check for your SSH port

SSH connection issues

# Verify SSH key permissions on your local machine (PowerShell example)
# Ensure your private key file (e.g., id_rsa) is protected
icacls .\ssh-keys\your_private_key_file # Should typically only grant access to your user

# Check authorized_keys in the container
docker exec hexo-blog-stable ls -la /home/hexo/.ssh/
docker exec hexo-blog-stable cat /home/hexo/.ssh/authorized_keys # Verify your public key is present and correct

# Check SSH service status in container
docker exec hexo-blog-stable ps aux | grep sshd

# Verbose SSH connection test from your local machine
ssh -i .\ssh-keys\your_private_key_file -p 2222 -vvv hexo@localhost

Nginx issues / Web service not accessible

# Test Nginx configuration in container
docker exec hexo-blog-stable nginx -t

# Check Nginx logs in container
docker exec hexo-blog-stable tail -f /var/log/nginx/error.log
docker exec hexo-blog-stable tail -f /var/log/nginx/access.log

# Check Nginx status in container
docker exec hexo-blog-stable ps aux | grep nginx

# Test health endpoint
curl http://localhost:8080/health

Git Deployment Failures

# Check permissions of the bare repository in the container
docker exec hexo-blog-stable ls -la /home/hexo/hexo.git/

# Check the deployment log in the container
docker exec hexo-blog-stable cat /var/log/container/deployment.log

# Test Git push with verbosity
git push deploy main -vvv

Version Information

v0.0.3 (Current Stable)

• ✅ Smart Log Size Control: Implemented and tested log rotation for deployment.log (1MB limit, keeps 5 backups).
• ✅ SSH Stability: Resolved SSH login failures by correcting authorized_keys permissions within the container post-startup.
• ✅ Test Suite Enhancements: Updated and validated run_test.ps1 and functional_test.ps1 for v0.0.3.
• ✅ Documentation: Updated README files to reflect v0.0.3 as the latest stable version.
• Focus on stability and core functionality.

v0.0.2

• Enhanced security with advanced headers (CSP, Referrer-Policy)
• Intelligent log rotation with 10MB file size limit (initial implementation)
• Dynamic PUID/PGID support for proper file ownership
• Dedicated /health endpoint for enhanced monitoring
• Improved SSH security (MaxAuthTries, ClientAlive settings)
• Heredoc syntax for better script readability
• Minimal production image (removed vim, nodejs, npm)
• Enhanced deployment logging with detailed file tracking
• Advanced service monitoring with automatic recovery
• Smart configuration template rendering

v0.0.1

• Implemented multi-stage Docker build
• Integrated SSH and Nginx services
• Template-based configuration system
• Colored logging output
• Automatic service monitoring and restart
• Health check functionality
• Git automated deployment support
• Security hardening configuration

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/YourFeature)
3. Make your changes
4. Test the Docker build (docker build -f Dockerfile_v0.0.3 -t hexo-blog:test .)
5. Commit your changes (git commit -m 'Add some feature')
6. Push to the branch (git push origin feature/YourFeature)
7. Submit a pull request

File Structure

dockerfiledir/
├── Dockerfile_v0.0.3          # Current stable Dockerfile
├── Dockerfile_v0.0.4          # Previous development Dockerfile (archived)
├── README.md                  # This file (English documentation)
├── README_zh.md               # Chinese documentation
├── README_QUICK_START_SIMPLE.md
├── README_QUICK_START_COMPLETE.md
├── start.sh                   # Main entrypoint script for the container
├── arch/                      # Archived Dockerfiles (v0.0.1, v0.0.2)
├── doc/                       # Additional documentation
│   ├── COMPREHENSIVE_VERSION_SUMMARY.md
│   └── ...
└── test/
    └── v0.0.3/
        └── windows/             # Test scripts for v0.0.3
            ├── run_test.ps1
            ├── functional_test.ps1
            ├── log_rotation_test.ps1
            ├── cleanup_test.ps1
            └── README.md        # Test guide for v0.0.3

License

This project is open source and available under the MIT License.

🔗 Related Resources

• 📖 Chinese Documentation: README_zh.md
• 📋 Complete Version History: Comprehensive Version Summary
• 🚀 Quick Deployment Guide: 30-Second Deployment
• 📖 Detailed Configuration Guide: Complete Deployment Documentation
• 🧪 Test Guide (v0.0.3): test/v0.0.3/windows/README.md
• 📊 Technical Documentation (v0.0.3): doc/summary/v0.0.3

---

Project Status: ✅ Production Ready
Maintenance Status: 🔄 Actively Maintained
Technical Support: 📧 Via GitHub Issues
Last Updated: May 30, 2025