nextav/docs/archive/deployment-legacy/DEPLOYMENT_GUIDE.md

NextAV Deployment Guide

Overview

NextAV is a Next.js application that provides media library management with SQLite database storage. This guide covers Docker deployment, troubleshooting, and best practices for the NextAV application.

Prerequisites

• Docker and Docker Compose installed
• At least 4GB of available disk space
• Port 3000 available

Quick Start

1. Clone and Setup

git clone <repository-url>
cd nextav

2. Environment Configuration

Create a .env file in the docker directory:

cd docker
cp .env.example .env
# Edit .env with your configuration

3. Create Required Directories

mkdir -p data media
chmod 755 data media

4. Build and Run

# Build the Docker image
docker build -t nextav:latest ..

# Start the application
docker compose up -d

5. Verify Deployment

# Check container status
docker compose ps

# Test health endpoint
curl http://localhost:3000/api/health

# Access the application
open http://localhost:3000

Configuration

Environment Variables

Variable	Default	Description
DB_PATH	./data	Path to database storage directory
MEDIA_PATH	./media	Path to media files directory
DB_FILE	/app/data/media.db	Database file path inside container
NEXT_PUBLIC_MEDIA_ROOT	/app/media	Media root path for the application

Volume Mounts

• ./data:/app/data - Database and application data
• ./media:/app/media - Media files storage

Troubleshooting

Database Access Issues

Problem: SqliteError: unable to open database file

Solution:

1. Ensure data directory exists and has correct permissions:

   mkdir -p data
   chmod 755 data
   

2. Fix container permissions:

   docker exec -u root nextav-app chown -R nextjs:nodejs /app/data /app/media
   

3. Restart the container:

   docker compose restart nextav
   

Native Module Issues

Problem: Could not locate the bindings file. Tried: ... better_sqlite3.node

Solution:

1. Rebuild the Docker image:

   docker build --no-cache -t nextav:latest ..
   

2. Ensure build dependencies are available in Dockerfile

Container Health Issues

Problem: Container shows as "unhealthy"

Solution:

1. Check logs:

   docker compose logs nextav
   

2. Test health endpoint manually:

   curl http://localhost:3000/api/health
   

3. Verify database connectivity and permissions

Build Performance Issues

Problem: Docker build takes too long

Solutions:

1. Use multi-stage builds (already implemented)
2. Remove unnecessary packages from production stage
3. Use .dockerignore to exclude unnecessary files
4. Consider using build cache

Best Practices

Security

• Run container as non-root user (implemented)
• Use specific image tags instead of latest
• Regularly update base images
• Scan images for vulnerabilities

Performance

• Use multi-stage builds to reduce image size
• Implement proper caching strategies
• Monitor resource usage
• Use health checks for reliability

Data Persistence

• Use named volumes for production
• Regular database backups
• Monitor disk space usage
• Implement proper backup strategies

Monitoring

• Health check endpoint: /api/health
• Application logs: docker compose logs nextav
• Resource monitoring: docker stats

Production Deployment

1. Environment Setup

# Production environment variables
NODE_ENV=production
DB_PATH=/var/lib/nextav/data
MEDIA_PATH=/var/lib/nextav/media

2. Reverse Proxy (Optional)

Configure Nginx or Traefik for SSL termination and load balancing.

3. Backup Strategy

# Database backup
docker exec nextav-app sqlite3 /app/data/media.db ".backup /app/data/backup.db"

# Volume backup
docker run --rm -v nextav_data:/data -v $(pwd):/backup alpine tar czf /backup/nextav_data.tar.gz -C /data .

4. Monitoring

• Set up log aggregation
• Monitor container health
• Track resource usage
• Set up alerts for failures

Maintenance

Regular Tasks

1. Update Dependencies: Monthly security updates
2. Database Maintenance: Regular backups and optimization
3. Log Rotation: Prevent disk space issues
4. Image Updates: Keep base images current

Troubleshooting Commands

# View logs
docker compose logs -f nextav

# Access container shell
docker exec -it nextav-app sh

# Check resource usage
docker stats nextav-app

# Restart services
docker compose restart nextav

# Update and rebuild
docker compose down
docker build -t nextav:latest ..
docker compose up -d

Support

For issues not covered in this guide:

1. Check application logs
2. Review Docker documentation
3. Consult Next.js deployment guides
4. Open an issue in the project repository

---

Last Updated: August 30, 2025 Version: 1.0.0