docs: update architecture documentation and manifests

Refine technical documentation to reflect current architecture, component structure, and routing conventions for the vcon console.
This commit is contained in:
Team Dark Devil committed 2026-11-17 21:22:55 +06:00
1 parent bb938c33c0
commit 367dd819f8
64 files changed
+910 -2661

No files matched your search

+3 -3
View File
@@ -7,10 +7,10 @@ FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT_SOCKET=4000
RUN mkdir -p /app/storage/data \
RUN apk add --no-cache su-exec \
&& mkdir -p /app/storage/data \
&& chown -R node:node /app/storage
COPY --from=dependencies --chown=node:node /app/node_modules ./node_modules
COPY --chown=node:node server ./server
USER node
EXPOSE 4000
CMD ["node", "server/index.js"]
CMD ["sh", "-c", "mkdir -p /app/storage/data && chown -R node:node /app/storage && exec su-exec node:node node server/index.js"]
+7 -5
View File
@@ -1,10 +1,12 @@
FROM node:22-alpine AS dependencies
WORKDIR /app
ENV NODE_ENV=development
COPY package.json package-lock.json* ./
RUN if [ -f package-lock.json ]; then npm ci; else npm install --no-audit --no-fund; fi
RUN if [ -f package-lock.json ]; then npm ci --include=dev; else npm install --include=dev --no-audit --no-fund; fi
FROM node:22-alpine AS builder
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
@@ -16,11 +18,11 @@ ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
RUN apk add --no-cache su-exec \
&& mkdir -p /app/storage/data \
&& chown -R node:node /app/storage
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
RUN mkdir -p /app/storage/data \
&& chown -R node:node /app/storage
USER node
EXPOSE 3000
CMD ["node", "server.js"]
CMD ["sh", "-c", "mkdir -p /app/storage/data && chown -R node:node /app/storage && exec su-exec node:node node server.js"]
+11 -19
View File
@@ -1,23 +1,15 @@
# Docker Deployment Manifest
# Docker & Coolify Deployment Manifest
## Purpose
Production container definitions and orchestration for DataStack's multi-service architecture (`docker/`):
Production container definitions for the split architecture:
- `web` (`Dockerfile.web`): Standalone Next.js 15 frontend, `/vcon/*` admin console, and REST API on port `3000` (runs as non-root user).
- `ingestion` (`Dockerfile.server`): Express + Socket.IO real-time ingestion server on port `4000` (runs as non-root user).
- `proxy` (`Dockerfile.proxy` + `coolify-nginx.conf`): Nginx reverse proxy on internal port `80`, forwarding `/socket.io/` to `ingestion:4000` and web traffic to `web:3000`.
- `postgres`: PostgreSQL 16 service with persistent `pgdata` volume storing `admin_users`, `admin_login_attempts`, `client_sdks`, and `admin_settings`.
- `redis`: Redis 7 service with persistent `redisdata` volume.
- `web`: standalone Next.js frontend and admin console on port 3000, running as a non-root user.
- `ingestion`: Express + Socket.IO process on port 4000, running as a non-root user.
- `proxy`: Nginx reverse proxy on internal port 80. Coolify routes the public domain to this service; `/socket.io/` is forwarded to ingestion and other paths to web.
- `redis`: private Compose service reserved for the planned shared-buffer integration; current application code does not consume it.
- `postgres`: private Compose service; the first-run admin setup/login helper stores the single bootstrap admin credential in `admin_users` using `pg`. Prisma-backed client/settings/audit metadata is not wired yet. Collected events must remain in CSV files.
## Coolify Compose Deployment
- Create a Git-based Docker Compose application from branch `main`.
- Set Base Directory to `/docker` and Compose Location to `/docker/docker-compose.yml`. Confirm the resolved file remains the repository's `docker/docker-compose.yml`. The `/docker` project directory is required because each service uses `build.context: ..` to reach the repository root; using `/` makes that context escape the checkout.
- Set `DATASTACK_ADMIN_EMAIL` in Coolify. Compose uses generated `SERVICE_HEX_32_DATABASENAME`, `SERVICE_PASSWORD_64_POSTGRES`, `SERVICE_REALBASE64_64_JWT`, `SERVICE_REALBASE64_64_ADMINSESSION`, and `SERVICE_REALBASE64_64_ADMININSTALL`; `DATABASE_URL` is assembled from the generated DB name/password.
- On first visit, copy `SERVICE_REALBASE64_64_ADMININSTALL` from Coolify into `/vcon/setup`, confirm the `DATASTACK_ADMIN_EMAIL` configured in Coolify, choose the first admin password, and keep generated secrets in Coolify. The API enforces the configured email and setup closes after the first account is persisted.
- Add the public domain to service `proxy` at internal port `80`. Coolify manages proxy labels in its normal Compose mode; do not enable Raw Compose mode or add direct host port mappings.
- The `web`, `ingestion`, Redis, and PostgreSQL services are private on the Compose network. Only the proxy is exposed to Coolify's domain proxy.
- The `datastack-data` named volume stores ingestion CSVs; `pgdata` stores PostgreSQL files and the bootstrap admin credential. Compose configures these named volumes for persistence; verify restart/redeploy behavior in the target Coolify runtime before relying on it. Do not delete the volumes or regenerate the DB name for an existing deployment. Back up before DB upgrades. DB password rotation requires changing the DB role as well as the Coolify value.
- The web container does not yet share/read `datastack-data`, and Redis is not wired into runtime code. Prisma-backed client/settings metadata remains future work; cross-process reads and general metadata durability are not established by these images.
- Health checks probe the web landing route, ingestion `/health`, proxy route, Redis ping, and PostgreSQL readiness using the generated `POSTGRES_DB` name. These checks do not establish application-level shared-storage readiness.
## Shared Volumes & Networking
- Both `web` and `ingestion` mount the `datastack-data` volume at `/app/storage/data`, ensuring CSV partitions written by either process are immediately visible across the platform.
- Both `web` and `ingestion` connect to `postgres` via `DATABASE_URL` over the private Compose network, synchronizing client registrations, revocation status, and runtime settings automatically.
- `web` communicates with `ingestion` via `INGESTION_INTERNAL_URL="http://ingestion:4000"` for live health metrics and manual buffer flushes.