feat: add deployment documentation and Docker configuration
- Introduced a comprehensive deployment guide for NextAV, detailing steps for building and pushing Docker images to a private registry. - Added a new docker-compose.yml file for service orchestration, including configurations for NextAV and Nginx. - Updated CLAUDE.md with guidelines for creating documentation and managing Docker images. - Created a PRIVATE_DOCKER_REPO.md file outlining tagging and pushing images to the private Docker repository.
This commit is contained in:
parent
854afd4c41
commit
158f9f7a23
|
|
@ -33,6 +33,12 @@ Deployment:
|
|||
2. Dockerfile should be defined
|
||||
3. docker-compose.yml should be defined.
|
||||
|
||||
Private Docker Image Repo:
|
||||
http://192.168.2.212:3000/tigeren/
|
||||
|
||||
|
||||
Development Rules:
|
||||
1. Everytime after making all the changes, run 'pnpm build' to verify the changes are compiling correct.
|
||||
2. Once added debug logs, don't delete it until told so.
|
||||
3. When creating guideline doc, place it under folder docs with markdown format
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,46 @@
|
|||
version: '3.8'
|
||||
|
||||
services:
|
||||
nextav:
|
||||
image: ${REGISTRY_URL:-192.168.2.212:3000}/${IMAGE_NAME:-tigeren/nextav}:${IMAGE_TAG:-latest}
|
||||
container_name: nextav-app
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- ${DB_PATH:-./data}:/app/data
|
||||
- ${MEDIA_PATH:-./media}:/app/media
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
- DATABASE_URL=${DATABASE_URL:-file:///app/data/nextav.db}
|
||||
- NEXT_PUBLIC_MEDIA_ROOT=${NEXT_PUBLIC_MEDIA_ROOT:-/app/media}
|
||||
- NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
|
||||
- NEXTAUTH_URL=${NEXTAUTH_URL}
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
networks:
|
||||
- nextav-network
|
||||
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
container_name: nextav-nginx
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "${HTTP_PORT:-80}:80"
|
||||
- "${HTTPS_PORT:-443}:443"
|
||||
volumes:
|
||||
- ./nginx.conf:/etc/nginx/nginx.conf:ro
|
||||
- ${SSL_CERT_PATH:-./ssl/cert.pem}:/etc/nginx/ssl/cert.pem:ro
|
||||
- ${SSL_KEY_PATH:-./ssl/key.pem}:/etc/nginx/ssl/key.pem:ro
|
||||
depends_on:
|
||||
- nextav
|
||||
networks:
|
||||
- nextav-network
|
||||
|
||||
networks:
|
||||
nextav-network:
|
||||
driver: bridge
|
||||
|
|
@ -0,0 +1,258 @@
|
|||
# NextAV Deployment Guide
|
||||
|
||||
This guide will help you deploy NextAV using Docker for a production-ready setup.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- Docker & Docker Compose
|
||||
- At least 2GB RAM and 10GB disk space
|
||||
- FFmpeg (for thumbnail generation)
|
||||
|
||||
### 1. Clone and Setup
|
||||
```bash
|
||||
git clone <your-repo-url> nextav
|
||||
cd nextav
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
```bash
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env with your settings
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 3. Deploy with Docker
|
||||
```bash
|
||||
# Make deploy script executable
|
||||
chmod +x deploy.sh
|
||||
|
||||
# Run deployment
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
### 4. Access NextAV
|
||||
Open your browser to `http://localhost:3000`
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
### Using Docker Compose
|
||||
```bash
|
||||
# Build and start
|
||||
docker-compose up -d --build
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f nextav
|
||||
|
||||
# Stop services
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Production with SSL (Optional)
|
||||
```bash
|
||||
# For production with SSL
|
||||
docker-compose --profile production up -d
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `DATABASE_URL` | SQLite database path | `file:./data/nextav.db` |
|
||||
| `NODE_ENV` | Environment mode | `production` |
|
||||
| `NEXT_PUBLIC_BASE_URL` | Base URL for the app | `http://localhost:3000` |
|
||||
| `NEXT_PUBLIC_MEDIA_ROOT` | Media library root | `/app/media` |
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
nextav/
|
||||
├── data/ # Database and app data
|
||||
├── media/ # Media libraries
|
||||
├── ssl/ # SSL certificates (optional)
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── .env
|
||||
└── deploy.sh
|
||||
```
|
||||
|
||||
## Media Libraries Setup
|
||||
|
||||
### Adding Media Libraries
|
||||
1. Create directories in the `media/` folder:
|
||||
```bash
|
||||
mkdir -p media/videos media/photos
|
||||
```
|
||||
|
||||
2. Mount your existing media:
|
||||
```bash
|
||||
# Example: mount existing photo library
|
||||
docker-compose down
|
||||
# Edit docker-compose.yml to add your volume
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Volume Mapping Examples
|
||||
In `docker-compose.yml`:
|
||||
```yaml
|
||||
volumes:
|
||||
- /path/to/your/media:/app/media/yourlibrary
|
||||
- /path/to/another/library:/app/media/another
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### SSL Certificates
|
||||
```bash
|
||||
# Create SSL directory
|
||||
mkdir ssl
|
||||
|
||||
# Generate self-signed certificates (for testing)
|
||||
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
|
||||
-keyout ssl/key.pem -out ssl/cert.pem
|
||||
|
||||
# For production, use Let's Encrypt certificates
|
||||
```
|
||||
|
||||
### Reverse Proxy (Nginx)
|
||||
The production profile includes Nginx with:
|
||||
- SSL termination
|
||||
- Gzip compression
|
||||
- Security headers
|
||||
- WebSocket support
|
||||
|
||||
### Health Checks
|
||||
The application includes health checks at `/api/health` which verify:
|
||||
- Database connectivity
|
||||
- Media directory accessibility
|
||||
- Application responsiveness
|
||||
|
||||
## Monitoring
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# All services
|
||||
docker-compose logs -f
|
||||
|
||||
# Specific service
|
||||
docker-compose logs -f nextav
|
||||
```
|
||||
|
||||
### Service Status
|
||||
```bash
|
||||
docker-compose ps
|
||||
docker stats
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Port 3000 already in use:**
|
||||
```bash
|
||||
# Check what's using port 3000
|
||||
lsof -i :3000
|
||||
|
||||
# Use different port
|
||||
docker-compose up -d --scale nextav=1 --build
|
||||
```
|
||||
|
||||
**Database permission issues:**
|
||||
```bash
|
||||
# Fix permissions
|
||||
sudo chown -R 1001:1001 ./data
|
||||
```
|
||||
|
||||
**FFmpeg not found:**
|
||||
```bash
|
||||
# Ensure FFmpeg is available
|
||||
which ffmpeg
|
||||
# Or use Docker container
|
||||
```
|
||||
|
||||
### Reset Everything
|
||||
```bash
|
||||
# Stop and remove containers
|
||||
docker-compose down
|
||||
|
||||
# Remove volumes (WARNING: deletes data)
|
||||
docker-compose down -v
|
||||
|
||||
# Rebuild and start
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
## Updates
|
||||
|
||||
### Updating NextAV
|
||||
```bash
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# Rebuild and restart
|
||||
docker-compose down
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
### Database Updates
|
||||
For database schema changes:
|
||||
```bash
|
||||
# Backup database
|
||||
cp data/nextav.db data/nextav.db.backup
|
||||
|
||||
# Apply updates (if needed)
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
### Basic Security
|
||||
- Uses non-root user in container
|
||||
- Runs with minimal privileges
|
||||
- Includes security headers in production
|
||||
|
||||
### Production Hardening
|
||||
- Use proper SSL certificates
|
||||
- Configure firewall rules
|
||||
- Set up log rotation
|
||||
- Use secrets management for sensitive data
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Resource Limits
|
||||
Edit `docker-compose.yml` to set limits:
|
||||
```yaml
|
||||
services:
|
||||
nextav:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2.0'
|
||||
memory: 2G
|
||||
reservations:
|
||||
cpus: '0.5'
|
||||
memory: 512M
|
||||
```
|
||||
|
||||
### Database Optimization
|
||||
- SQLite is optimized for read-heavy workloads
|
||||
- Consider PostgreSQL for high-traffic sites
|
||||
- Regular database maintenance recommended
|
||||
|
||||
## Support
|
||||
|
||||
For issues and feature requests, please check:
|
||||
1. Docker logs: `docker-compose logs`
|
||||
2. Health endpoint: `curl http://localhost:3000/api/health`
|
||||
3. System resources: `docker stats`
|
||||
|
||||
|
||||
## Build/Push Docker image to private repo
|
||||
Usage:
|
||||
# Build & push to private registry
|
||||
docker build -t 192.168.2.212:3000/tigeren/nextav:latest .
|
||||
docker push 192.168.2.212:3000/tigeren/nextav:latest
|
||||
|
|
@ -0,0 +1,261 @@
|
|||
# NextAV Deployment Guide
|
||||
|
||||
## Overview
|
||||
This guide covers deploying NextAV to a private Docker registry and production server.
|
||||
|
||||
## Prerequisites
|
||||
- Docker & Docker Compose installed
|
||||
- Access to private registry (e.g., 192.168.2.212:3000)
|
||||
- SSL certificates for HTTPS (optional for local deployment)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Build & Push to Private Registry
|
||||
|
||||
```bash
|
||||
# Build the image
|
||||
docker build -t 192.168.2.212:3000/tigeren/nextav:latest .
|
||||
|
||||
# Push to private registry
|
||||
docker push 192.168.2.212:3000/tigeren/nextav:latest
|
||||
|
||||
# Verify push
|
||||
curl http://192.168.2.212:3000/v2/_catalog
|
||||
```
|
||||
|
||||
### 2. Deploy to Production Server
|
||||
|
||||
```bash
|
||||
# Copy deployment files to server
|
||||
scp -r docker/ user@server:/path/to/nextav/
|
||||
|
||||
# SSH to server
|
||||
ssh user@server
|
||||
cd /path/to/nextav/docker/
|
||||
|
||||
# Configure environment
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
|
||||
# Deploy
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Detailed Deployment Steps
|
||||
|
||||
### Local Development
|
||||
```bash
|
||||
# Build locally
|
||||
docker build -t nextav:dev .
|
||||
|
||||
# Run locally
|
||||
docker-compose -f docker-compose.yml up -d
|
||||
```
|
||||
|
||||
### Production with Private Registry
|
||||
|
||||
#### Step 1: Configure Private Registry Access
|
||||
```bash
|
||||
# Add insecure registry to Docker daemon
|
||||
echo '{ "insecure-registries": ["192.168.2.212:3000"] }' | \
|
||||
sudo tee /etc/docker/daemon.json
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
#### Step 2: Build & Tag
|
||||
```bash
|
||||
# Build with registry tag
|
||||
docker build -t 192.168.2.212:3000/tigeren/nextav:latest .
|
||||
docker build -t 192.168.2.212:3000/tigeren/nextav:v1.0.0 .
|
||||
```
|
||||
|
||||
#### Step 3: Push to Registry
|
||||
```bash
|
||||
# Push latest
|
||||
docker push 192.168.2.212:3000/tigeren/nextav:latest
|
||||
|
||||
# Push versioned
|
||||
docker push 192.168.2.212:3000/tigeren/nextav:v1.0.0
|
||||
```
|
||||
|
||||
#### Step 4: Deploy on Target Server
|
||||
|
||||
**On production server:**
|
||||
```bash
|
||||
# Create deployment directory
|
||||
mkdir -p /opt/nextav
|
||||
cd /opt/nextav
|
||||
|
||||
# Copy deployment files
|
||||
cp docker/docker-compose.yml .
|
||||
cp docker/.env.example .env
|
||||
|
||||
# Create SSL directory (optional)
|
||||
mkdir -p ssl
|
||||
# Copy your SSL certificates to ssl/cert.pem and ssl/key.pem
|
||||
|
||||
# Configure environment
|
||||
nano .env
|
||||
```
|
||||
|
||||
**Edit .env file:**
|
||||
```bash
|
||||
REGISTRY_URL=192.168.2.212:3000
|
||||
IMAGE_NAME=tigeren/nextav
|
||||
IMAGE_TAG=latest
|
||||
|
||||
# Set your domain
|
||||
NEXTAUTH_URL=https://your-domain.com
|
||||
NEXTAUTH_SECRET=your-secure-secret
|
||||
|
||||
# Adjust paths if needed
|
||||
DB_PATH=./data
|
||||
MEDIA_PATH=./media
|
||||
```
|
||||
|
||||
**Deploy:**
|
||||
```bash
|
||||
# Pull and deploy
|
||||
docker-compose pull
|
||||
docker-compose up -d
|
||||
|
||||
# Check status
|
||||
docker-compose ps
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `REGISTRY_URL` | Private registry URL | 192.168.2.212:3000 |
|
||||
| `IMAGE_NAME` | Image name | tigeren/nextav |
|
||||
| `IMAGE_TAG` | Image tag | latest |
|
||||
| `NEXT_PUBLIC_MEDIA_ROOT` | Media directory | /app/media |
|
||||
| `DATABASE_URL` | Database file path | file:///app/data/nextav.db |
|
||||
| `NEXTAUTH_SECRET` | Auth secret | required |
|
||||
| `NEXTAUTH_URL` | Application URL | required |
|
||||
| `SSL_CERT_PATH` | SSL certificate path | ./ssl/cert.pem |
|
||||
| `SSL_KEY_PATH` | SSL private key path | ./ssl/key.pem |
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
docker/
|
||||
├── .env.example # Environment template
|
||||
├── docker-compose.yml # Production compose
|
||||
├── nginx.conf # Nginx configuration
|
||||
└── ssl/ # SSL certificates (optional)
|
||||
```
|
||||
|
||||
## SSL Setup (Production)
|
||||
|
||||
### Using Let's Encrypt
|
||||
```bash
|
||||
# Install certbot
|
||||
sudo apt install certbot
|
||||
|
||||
# Generate certificates
|
||||
sudo certbot certonly --standalone -d your-domain.com
|
||||
|
||||
# Copy certificates
|
||||
cp /etc/letsencrypt/live/your-domain.com/fullchain.pem ssl/cert.pem
|
||||
cp /etc/letsencrypt/live/your-domain.com/privkey.pem ssl/key.pem
|
||||
```
|
||||
|
||||
### Using Self-Signed (Development)
|
||||
```bash
|
||||
# Generate self-signed certificates
|
||||
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
|
||||
-keyout ssl/key.pem -out ssl/cert.pem
|
||||
```
|
||||
|
||||
## Monitoring & Maintenance
|
||||
|
||||
### Health Checks
|
||||
```bash
|
||||
# Check application health
|
||||
curl http://localhost:3000/api/health
|
||||
|
||||
# Check nginx health
|
||||
curl http://localhost/health
|
||||
```
|
||||
|
||||
### Logs
|
||||
```bash
|
||||
# View all logs
|
||||
docker-compose logs -f
|
||||
|
||||
# View specific service logs
|
||||
docker-compose logs -f nextav
|
||||
docker-compose logs -f nginx
|
||||
```
|
||||
|
||||
### Updates
|
||||
```bash
|
||||
# Update to latest version
|
||||
docker-compose pull
|
||||
docker-compose up -d
|
||||
|
||||
# Update to specific version
|
||||
# Edit .env: IMAGE_TAG=v1.0.1
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Backup
|
||||
```bash
|
||||
# Backup database and media
|
||||
tar -czf backup-$(date +%Y%m%d).tar.gz data/ media/
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Registry connection failed:**
|
||||
```bash
|
||||
# Check registry accessibility
|
||||
curl http://192.168.2.212:3000/v2/_catalog
|
||||
|
||||
# Check Docker daemon configuration
|
||||
cat /etc/docker/daemon.json
|
||||
```
|
||||
|
||||
**Permission issues:**
|
||||
```bash
|
||||
# Fix file permissions
|
||||
sudo chown -R $USER:$USER data/ media/
|
||||
```
|
||||
|
||||
**Port conflicts:**
|
||||
```bash
|
||||
# Check port usage
|
||||
sudo netstat -tulpn | grep :3000
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
```bash
|
||||
# Run in debug mode
|
||||
docker-compose up
|
||||
# or
|
||||
docker-compose logs -f nextav
|
||||
```
|
||||
|
||||
## One-Click Deployment
|
||||
|
||||
Use the provided deployment script:
|
||||
```bash
|
||||
# Make executable
|
||||
chmod +x deploy.sh
|
||||
|
||||
# Run deployment
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Change default passwords and secrets
|
||||
- Use HTTPS in production
|
||||
- Regularly update images
|
||||
- Monitor logs for suspicious activity
|
||||
- Backup database regularly
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
# 打标规范
|
||||
https://docs.gitea.com/1.21/usage/packages/container
|
||||
|
||||
## build an image with tag
|
||||
docker build -t {registry}/{owner}/{image}:{tag} .
|
||||
## name an existing image with tag
|
||||
docker tag {some-existing-image}:{tag} {registry}/{owner}/{image}:{tag}
|
||||
## push an image
|
||||
docker push {registry}/{owner}/{image}:{tag}
|
||||
|
||||
# 给现有的image打标
|
||||
docker tag magicdoc-magicdoc-api:latest 192.168.2.212:3000/tigeren/magicdoc-magicdoc-api
|
||||
|
||||
# 推送
|
||||
docker tag magicdoc-magicdoc-api:latest 192.168.2.212:3000/tigeren/magicdoc-magicdoc-api
|
||||
docker push 192.168.2.212:3000/tigeren/magicdoc-magicdoc-api
|
||||
|
||||
docker tag backend-api:latest 192.168.2.212:3000/tigeren/backend-api
|
||||
docker push 192.168.2.212:3000/tigeren/backend-api:latest
|
||||
|
||||
# 访问查看images
|
||||
http://192.168.2.212:3000/tigeren/
|
||||
|
||||
# orbstack配置： settings -> docker
|
||||
{
|
||||
"insecure-registries" : [
|
||||
"192.168.2.212:3000"
|
||||
]
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue