xorbitlab
/
nextav
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

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:
tigeren 2025-08-30 11:59:56 +00:00
parent 854afd4c41
commit 158f9f7a23
5 changed files with 601 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CLAUDE.md
View File

@ -33,6 +33,12 @@ Deployment:
2. Dockerfile should be defined 2. Dockerfile should be defined
3. docker-compose.yml should be defined. 3. docker-compose.yml should be defined.
Private Docker Image Repo:
http://192.168.2.212:3000/tigeren/
Development Rules: Development Rules:
1. Everytime after making all the changes, run 'pnpm build' to verify the changes are compiling correct. 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. 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

46
docker/docker-compose.yml Normal file
View File

@ -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

258
docs/DEPLOYMENT.md Normal file
View File

@ -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

261
docs/DEPLOYMENT_GUIDE.md Normal file
View File

@ -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

30
docs/PRIVATE_DOCKER_REPO.md Normal file
View File

@ -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"
]
}