Files
Team Dark Devil 89e4d68690 feat(auth): harden session management and security
- Implement server-side session revocation on logout
- Add IP extraction utility and admin setup error handling
- Improve error codes and response consistency for auth endpoints
- Refine landing page redirect logic to handle transient DB outages
- Update deployment documentation and configuration defaults
2026-11-19 20:22:01 +06:00

4.6 KiB
Raw Permalink Blame History

Installation & Deployment Guide

This guide explains how to install and self-host DataStack on your own server or cloud VPS.


Prerequisites

Before starting, ensure your system meets the following minimum requirements:

  • Operating System: Linux (Ubuntu 22.04+, Debian 12+, Alpine), macOS, or Windows WSL2.
  • Docker Engine: Docker v24.0+ and Docker Compose v2.20+.
  • System Resources:
    • Minimum: 1 vCPU, 1 GB RAM, 10 GB disk space.
    • Recommended: 2 vCPU, 2–4 GB RAM, SSD storage scaled to your expected data volume.
  • Networking: Ports 80 (HTTP) and 443 (HTTPS) accessible via your reverse proxy or cloud firewall.

DataStack includes a complete, production-ready Docker Compose stack located in the docker/ directory.

1. Clone the Repository

git clone https://github.com/vibtoolshq/datastack.git
cd datastack

2. Configure Environment Variables

Copy the example environment configuration:

cp .env.example .env

Generate secure, random 32+ character secrets for production:

# In Linux / macOS, generate 48-char random hex keys:
openssl rand -hex 32

Edit .env and fill in the required variables:

# Production Security Secrets (Minimum 32 characters each)
DATASTACK_ADMIN_SESSION_SECRET=your-random-32-plus-char-session-secret-here
DATASTACK_JWT_SECRET=your-random-32-plus-char-client-jwt-secret-here
DATASTACK_ADMIN_SETUP_KEY=your-random-32-plus-char-admin-setup-key-here
DATASTACK_INTERNAL_SECRET=your-random-32-plus-char-internal-service-secret-here

# Administrator Initial Email
DATASTACK_ADMIN_EMAIL=admin@yourcompany.com

3. Launch the Stack

Run Docker Compose from the project root:

docker compose -f docker/docker-compose.yml up -d

The stack launches 5 containers:

  1. proxy: Nginx reverse proxy exposed on port 80, routing /socket.io/ to port 4000 and all other routes to port 3000.
  2. web: Next.js 15 standalone server running on port 3000.
  3. ingestion: Dedicated Express + Socket.IO ingestion server running on port 4000.
  4. postgres: PostgreSQL 16 database storing administrative credentials, SDK client records, and settings.
  5. redis: Redis 7 container running with --appendonly yes for crash-resilient queue buffering.

Method 2: Coolify Cloud / Self-Hosted PaaS

DataStack is optimized for deployment via Coolify:

  1. Create Resource: In Coolify, click + Add Resource → Docker Compose.
  2. Repository Settings:
    • Point to your DataStack Git repository.
    • Set Base Directory to / (so Compose build context .. from /docker resolves cleanly to the repository root; if an existing VPS deployment already has saved working Coolify paths, keep its current settings).
    • Set Docker Compose Location to /docker/docker-compose.yml.
  3. Domain Assignment:
    • Attach your custom domain (e.g. https://datastack.yourdomain.com) to the proxy service on internal port 80.
    • Enable automatic SSL/TLS via Coolify's built-in Let's Encrypt integration.
  4. Environment Variables:
    • Coolify automatically injects generated SERVICE_* variables for database and JWT secrets.
  5. Deploy: Click Deploy and monitor the build logs until all 5 services are healthy.

First-Run Administrator Setup (/vcon/setup)

Once the stack is running:

  1. Open your browser and navigate to:
    https://your-domain.example/vcon/setup
    
  2. You will be prompted to enter:
    • Administrator Email: Must match DATASTACK_ADMIN_EMAIL or your chosen admin email.
    • Administrator Password: Choose a strong password (minimum 8 characters).
    • Setup Security Key: Enter the exact value configured in DATASTACK_ADMIN_SETUP_KEY.
  3. Click Complete Initial Setup. You will be securely logged in and redirected to the /vcon/dashboard console.

Persistent Storage & Volumes

DataStack uses three named volumes to safeguard your data across container updates:

Volume Name Container Path Purpose
datastack-data /app/storage Contains /app/storage/data/{clientId}/{YYYY-MM-DD}.csv. Shared by web and ingestion.
pgdata /var/lib/postgresql/data Persists administrative users, client credentials, and settings.
redisdata /data Persists Redis Append-Only File (appendonly.aof) for unflushed event buffers.

Important

: When upgrading or redeploying containers, never execute docker compose down -v, as the -v flag deletes named volumes. Use standard docker compose down followed by docker compose up -d.