chore: establish cross-IDE synchronization protocol
Implement `.ai-rules`, formalize `MEMORY.md` as the source of truth, and initialize `docs/` structure to ensure consistent architectural context across development environments.
This commit is contained in:
1 parent
05407fd338
commit
4279da45bb
14 files changed
+1162
No files matched your search
@@ -0,0 +1,111 @@
|
||||
# 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.
|
||||
- Set **Base Directory** to `/docker`.
|
||||
- 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`.
|
||||
Reference in new issue
Block a user