2026-11-18 07:11:11 +06:00
# 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.
---
## Method 1: Docker Compose (Recommended)
DataStack includes a complete, production-ready Docker Compose stack located in the [`docker/` ](../../docker/ ) directory.
### 1. Clone the Repository
```bash
git clone https://github.com/vibtoolshq/datastack.git
cd datastack
```
### 2. Configure Environment Variables
Copy the example environment configuration:
```bash
cp .env.example .env
```
Generate secure, random 32+ character secrets for production:
```bash
# In Linux / macOS, generate 48-char random hex keys:
openssl rand -hex 32
```
Edit `.env` and fill in the required variables:
```dotenv
# 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:
```bash
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 ](https://coolify.io/ ):
1. **Create Resource** : In Coolify, click ** + Add Resource** → **Docker Compose** .
2. **Repository Settings** :
- Point to your DataStack Git repository.
2026-11-19 20:22:01 +06:00
- 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).
2026-11-18 07:11:11 +06:00
- 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:
```text
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`.