KUNO

Demo

Features

🌐 Supported Languages

Quick Start

🚀 One-Click Deployment (Recommended)

# 1. Create dedicated directory (recommended: /opt)
sudo mkdir -p /opt/kuno
cd /opt/kuno
# 2. Download and execute deployment script
curl -sSL "https://raw.githubusercontent.com/xuemian168/kuno/main/deploy-from-hub.sh?$(date +%s)" -o deploy.sh && chmod +x deploy.sh && ./deploy.sh

Manual Deployment

# 1. Create dedicated directory
sudo mkdir -p /opt/kuno
cd /opt/kuno
# 2. Create data directory
mkdir -p ./blog-data
# 3. Run container
docker run -d \
 --name kuno \
 --restart unless-stopped \
 -p 80:80 \
 -v /opt/kuno/blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL="http://localhost/api" \
 -e DB_PATH="/app/data/blog.db" \
 -e GIN_MODE="release" \
 -e NODE_ENV="production" \
 -e JWT_SECRET="your-secure-secret-key" \
 ictrun/kuno:latest

🛠️ Development Setup

Prerequisites

Local Development

🐳 Docker Hub Deployment Options

Option 1: Using Docker Compose (Recommended)

# Download the compose file
curl -O https://raw.githubusercontent.com/xuemian168/kuno/main/docker-compose.hub.yml
# Configure environment
cp .env.hub.example .env
# Edit .env with your settings
# Deploy
docker-compose -f docker-compose.hub.yml up -d

Option 2: Direct Docker Run

# Create dedicated directory
cd /opt/kuno
# Run container with bind mount (modify NEXT_PUBLIC_API_URL!)
docker run -d \
 --name kuno \
 --restart unless-stopped \
 -p 80:80 \
 -v /opt/kuno/blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL=https://your-api-domain.com/api \
 -e DB_PATH=/app/data/blog.db \
 ictrun/kuno:latest

Available Tags

🔧 Configuration

Environment Variables

First Time Setup

📊 Management Commands

# Check status
docker ps | grep kuno
# View logs
docker logs kuno
# Backup data (from /opt/kuno)
cd /opt/kuno
sudo tar -czf blog-backup-$(date +%Y%m%d).tar.gz ./blog-data
# Stop and remove
docker stop kuno
docker rm kuno

🔄 Upgrade Instructions

🐳 For Docker Deployment (Single Container)

Step 1: Backup Your Data (Recommended)

# Create backup directory
mkdir -p ./backups/$(date +%Y%m%d_%H%M%S)
# Backup the data volume
docker run --rm -v blog-data:/data -v $(pwd)/backups/$(date +%Y%m%d_%H%M%S):/backup alpine sh -c "cd /data && tar czf /backup/blog-data-backup.tar.gz ."
# Or if using bind mount, simply copy the directory
cd /opt/kuno
cp -r ./blog-data ./backups/$(date +%Y%m%d_%H%M%S)/

Step 2: Pull the Latest Image

docker pull ictrun/kuno:latest

Step 3: Stop and Remove the Old Container

docker stop kuno
docker rm kuno

Step 4: Start the New Container

# If using named volume (recommended)
docker run -d \
 --name kuno \
 --restart unless-stopped \
 -p 80:80 \
 -v blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL=https://your-domain.com/api \
 -e DB_PATH=/app/data/blog.db \
 ictrun/kuno:latest
# If using bind mount
cd /opt/kuno
docker run -d \
 --name kuno \
 --restart unless-stopped \
 -p 80:80 \
 -v /opt/kuno/blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL=https://your-domain.com/api \
 -e DB_PATH=/app/data/blog.db \
 ictrun/kuno:latest

Step 5: Verify the Upgrade

# Check container status
docker ps | grep kuno
# Check logs for any errors
docker logs kuno
# Test the application
curl -f http://localhost/api/categories || echo "API check failed"

🐳 For Docker Compose Deployment

Step 1: Backup Your Data (Recommended)

# Create backup directory
mkdir -p ./backups/$(date +%Y%m%d_%H%M%S)
# Stop services temporarily for consistent backup
docker-compose stop
# Backup the data volume
docker run --rm -v blog_blog_data:/data -v $(pwd)/backups/$(date +%Y%m%d_%H%M%S):/backup alpine sh -c "cd /data && tar czf /backup/blog-data-backup.tar.gz ."
# Or backup the entire compose environment
cp -r ./data ./backups/$(date +%Y%m%d_%H%M%S)/ 2>/dev/null || true
cp docker-compose.yml ./backups/$(date +%Y%m%d_%H%M%S)/ 2>/dev/null || true
cp .env ./backups/$(date +%Y%m%d_%H%M%S)/ 2>/dev/null || true
# Restart services
docker-compose start

Step 2: Pull the Latest Images

docker-compose pull

Step 3: Upgrade with Zero Downtime

# Method 1: Rolling update (recommended for production)
docker-compose up -d --force-recreate --remove-orphans
# Method 2: Complete restart (if you need to stop everything)
docker-compose down && docker-compose up -d

Step 4: Clean Up Old Images (Optional)

# Remove unused images to free up space
docker image prune -f
# Or remove specific old images
docker images | grep kuno | grep -v latest | awk '{print 3ドル}' | xargs docker rmi 2>/dev/null || true

Step 5: Verify the Upgrade

# Check all services status
docker-compose ps
# Check logs for any errors
docker-compose logs -f --tail=50
# Test the application
curl -f http://localhost:3000 || echo "Frontend check failed"
curl -f http://localhost:8080/api/categories || echo "API check failed"

🔄 Automated Upgrade Script

For Docker Deployment

#!/bin/bash
# save as upgrade-docker.sh
set -e
echo "🚀 Starting Docker deployment upgrade..."
# Configuration
CONTAINER_NAME="kuno"
IMAGE_NAME="ictrun/kuno:latest"
BACKUP_DIR="./backups/$(date +%Y%m%d_%H%M%S)"
# Create backup
echo "📦 Creating backup..."
mkdir -p "$BACKUP_DIR"
docker run --rm -v blog-data:/data -v "$BACKUP_DIR":/backup alpine sh -c "cd /data && tar czf /backup/blog-data-backup.tar.gz ."
# Pull latest image
echo "⬇️ Pulling latest image..."
docker pull "$IMAGE_NAME"
# Stop and remove old container
echo "🛑 Stopping old container..."
docker stop "$CONTAINER_NAME" 2>/dev/null || true
docker rm "$CONTAINER_NAME" 2>/dev/null || true
# Start new container
echo "🚀 Starting new container..."
docker run -d \
 --name "$CONTAINER_NAME" \
 --restart unless-stopped \
 -p 80:80 \
 -v blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL="${NEXT_PUBLIC_API_URL:-http://localhost/api}" \
 -e DB_PATH=/app/data/blog.db \
 "$IMAGE_NAME"
# Verify
echo "✅ Verifying upgrade..."
sleep 10
if docker ps | grep -q "$CONTAINER_NAME"; then
 echo "✅ Upgrade completed successfully!"
 echo "📄 Backup saved to: $BACKUP_DIR"
else
 echo "❌ Upgrade failed! Check logs: docker logs $CONTAINER_NAME"
 exit 1
fi

For Docker Compose Deployment

#!/bin/bash
# save as upgrade-compose.sh
set -e
echo "🚀 Starting Docker Compose deployment upgrade..."
# Configuration
BACKUP_DIR="./backups/$(date +%Y%m%d_%H%M%S)"
# Create backup
echo "📦 Creating backup..."
mkdir -p "$BACKUP_DIR"
docker-compose stop
docker run --rm -v blog_blog_data:/data -v "$BACKUP_DIR":/backup alpine sh -c "cd /data && tar czf /backup/blog-data-backup.tar.gz ."
cp -r ./data "$BACKUP_DIR/" 2>/dev/null || true
cp docker-compose.yml "$BACKUP_DIR/" 2>/dev/null || true
cp .env "$BACKUP_DIR/" 2>/dev/null || true
# Pull and upgrade
echo "⬇️ Pulling latest images..."
docker-compose pull
echo "🔄 Upgrading services..."
docker-compose up -d --force-recreate --remove-orphans
# Clean up
echo "🧹 Cleaning up old images..."
docker image prune -f
# Verify
echo "✅ Verifying upgrade..."
sleep 15
if docker-compose ps | grep -q "Up"; then
 echo "✅ Upgrade completed successfully!"
 echo "📄 Backup saved to: $BACKUP_DIR"
else
 echo "❌ Upgrade failed! Check logs: docker-compose logs"
 exit 1
fi

🛠️ Rollback Instructions

For Docker Deployment

# Stop the failed container
docker stop kuno && docker rm kuno
# Restore from backup (if needed)
docker run --rm -v blog-data:/data -v $(pwd)/backups/BACKUP_DATE:/backup alpine sh -c "cd /data && tar xzf /backup/blog-data-backup.tar.gz"
# Run the previous image version
docker run -d \
 --name kuno \
 --restart unless-stopped \
 -p 80:80 \
 -v blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL=https://your-domain.com/api \
 ictrun/kuno:PREVIOUS_TAG

For Docker Compose Deployment

# Edit docker-compose.yml to use previous image tag
# Then restart
docker-compose down
docker-compose up -d
# Restore data if needed
docker-compose stop
docker run --rm -v blog_blog_data:/data -v $(pwd)/backups/BACKUP_DATE:/backup alpine sh -c "cd /data && tar xzf /backup/blog-data-backup.tar.gz"
docker-compose start

📋 Upgrade Checklist

Manual Deployment

Development Mode

docker-compose up --build -d

Production Mode (with Nginx)

docker-compose -f docker-compose.prod.yml up --build -d

Architecture

Important Configuration Notes

Example Configurations

NEXT_PUBLIC_API_URL=http://localhost:8080/api

NEXT_PUBLIC_API_URL=https://yourdomain.com/api

Docker Volumes

Management Commands

Start Application

./start.sh

Stop Application

./stop.sh

View Logs

docker-compose logs -f

Restart Services

docker-compose restart

Clean Everything

docker-compose down -v
docker system prune -f

Password Recovery

When Admin Password is Forgotten

Step 1: Stop the Container

docker stop kuno

Step 2: Enable Recovery Mode

cd /opt/kuno
docker run -d \
 --name kuno_recovery \
 --restart unless-stopped \
 -p 80:80 \
 -v /opt/kuno/blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL="http://localhost/api" \
 -e DB_PATH="/app/data/blog.db" \
 -e RECOVERY_MODE="true" \
 ictrun/kuno:latest

Step 3: Check Reset Result

# View logs to confirm password reset
docker logs kuno_recovery
# Remove recovery container
docker rm -f kuno_recovery

Step 4: Start Blog Normally

# Run with normal mode
docker run -d \
 --name kuno \
 --restart unless-stopped \
 -p 80:80 \
 -v /opt/kuno/blog-data:/app/data \
 -e NEXT_PUBLIC_API_URL="http://localhost/api" \
 -e DB_PATH="/app/data/blog.db" \
 -e RECOVERY_MODE="false" \
 ictrun/kuno:latest

Step 5: Login with New Password

Step 6: Change Password Immediately

Security Notes

Troubleshooting Recovery Issues

Development

Local Development (without Docker)

Backend

cd backend
go mod download
go run cmd/server/main.go

Frontend

cd frontend
npm install
npm run dev

Building

Backend

cd backend
go build -o bin/server cmd/server/main.go

Frontend

cd frontend
npm run build
npm start

Troubleshooting

Common Issues

Health Checks

Logs

# All services
docker-compose logs -f
# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend

Production Considerations

Sponsorship

License