VPS Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides a comprehensive overview of the scripts and procedures for deploying the Sentiment Analysis application to a Virtual Private Server (VPS). The deployment strategy is heavily based on Docker and Docker Compose, offering several automated script-based options for different use cases, from a full production setup with a persistent database to a simple in-memory version.
The deployment process is designed to be automated, with shell scripts handling dependency installation, environment setup, and service orchestration. This ensures a consistent and repeatable deployment process. For more detailed checklists on pre-deployment, testing, and post-deployment monitoring, refer to the Deployment Checklist.
Deployment Architecture
The core of the VPS deployment relies on Docker and docker-compose to build and run the application services in containers. The scripts provided automate the setup of prerequisites like Docker itself, cloning the source code, and managing the container lifecycle.
Deployment Options
The repository offers multiple deployment scripts, each tailored for a specific scenario.
| Script | Description | Key Features |
|---|---|---|
deploy-vps.sh | Deploys the full application with a PostgreSQL database. | Production-ready, persistent data, requires .env.production setup. |
deploy-simple.sh | Deploys a lightweight version using in-memory storage. | Zero database setup, ultra-fast, auto-backup to JSON. Ideal for low-spec VPS. |
deploy-from-github.sh | Automates deployment directly from the GitHub repository. | Clones or pulls the latest code, installs Docker/Compose, builds and runs containers. |
vps-linux-deploy.sh | A one-command script that executes deploy-from-github.sh. | Simplifies initial setup on a fresh Linux VPS. |
deploy-minimal.py | A Python script to create a minimal deployment package. | Packages only essential files (src, models, minimal requirements) for a lightweight deployment. |
Sources: deploy-vps.sh, deploy-simple.sh, deploy-from-github.sh, vps-linux-deploy.sh, deploy-minimal.py
Automated Deployment from GitHub
A streamlined, one-command deployment is available for fresh Linux VPS environments. This process automates fetching the code, installing dependencies, and starting the application.
The following diagram illustrates the flow initiated by vps-linux-deploy.sh.
Deployment Scenarios
There are two primary deployment scenarios supported by the provided scripts: a full production deployment and a simple, in-memory deployment.
1. Full Production Deployment (deploy-vps.sh)
This script is intended for a production environment. It uses docker-compose.yml to orchestrate the services, including a PostgreSQL database for persistent storage.
Workflow:
- Environment Check: The script first checks for the existence of a
.env.productionfile. - Template Creation: If the file is not found, it creates a template with placeholder values and exits, prompting the user to edit it.
- Build & Deploy: Once the environment file is configured, it builds the Docker containers and starts them in detached mode (
-d). - Status Check: It waits for 10 seconds for the database to initialize and then displays the status of the running services using
docker-compose ps.
The following sequence diagram shows the process:
Sources: deploy-vps.sh:6-26
Environment Configuration
The deploy-vps.sh script requires a .env.production file. The following variables must be configured:
| Variable | Description | Example |
|---|---|---|
DB_PASSWORD | The password for the PostgreSQL database user. | change_this_password_123 |
DATABASE_URL | The connection string for the PostgreSQL database. | postgresql://admin:DB_PASSWORD@postgres:5432/sentiment_analysis |
NODE_ENV | The node environment. | production |
NEXTAUTH_SECRET | A secret key for NextAuth. | change_this_secret_key |
YOUTUBE_API_KEY | The API key for accessing YouTube data. | your_youtube_api_key_here |
Sources: deploy-vps.sh:10-15
2. Simple In-Memory Deployment (deploy-simple.sh)
This script provides a lightweight deployment option that does not require a database setup. It uses docker-compose.simple.yml and is ideal for testing or low-resource environments.
Key Features:
- In-Memory Storage: Data is stored in memory, with a JSON backup mechanism.
- Fast Performance: No database overhead.
- Resource-Efficient: Suitable for low-spec VPS with ~2-5MB RAM usage.
Workflow:
- Stop & Clean: The script stops any existing containers and prunes the Docker system to ensure a clean state.
- Build & Deploy: It builds the containers without cache (
--no-cache) and starts the services. - Health Check: After a 15-second wait, it performs a
curlrequest to a health check endpoint (/api/live-data?action=memory).
Sources: deploy-simple.sh:5-28
Minimal Deployment Package
The deploy-minimal.py script is a utility for creating a lightweight deployment package. It copies only the essential files and models into a deployment-minimal directory, reducing the overall size of the artifact that needs to be transferred to a server.
Essential Files Packaged:
src/directory- SVM and TF-IDF models (
.pklfiles) - Label encoder (
.pklfile) - Cleaned comments data (
.csv.gz) requirements-minimal.txtREADME.md
This is useful for environments where the full repository history and development-related files are not needed.
Sources: deploy-minimal.py:10-20
Deployment Checklist
The dashboard-next/DEPLOYMENT_CHECKLIST.md file provides a comprehensive checklist for ensuring a successful deployment. Key areas include:
- Pre-Deployment: Verifying code, builds, and tests.
- Deployment Steps: Options for Vercel, Docker, and traditional server setups.
- Environment Variables: Guidance on setting up
.env.local. - Post-Deployment Monitoring: Immediate and long-term checks for performance and user experience.
- Troubleshooting: Common issues like build failures and port conflicts.
- Security: Checklist for HTTPS, CORS, and rate limiting.
This document serves as a crucial guide for the entire deployment lifecycle, from preparation to post-launch monitoring.
Sources: dashboard-next/DEPLOYMENT_CHECKLIST.md