Skip to main content

​
Overview

Sciety is deployed as a containerized application using Docker. The platform supports multiple deployment targets:
  • Local development with Docker Compose
  • Production on Kubernetes using Helm charts
  • Staging environments for testing
This guide covers the initial setup and deployment prerequisites.

​
Prerequisites

Docker

Docker Engine 20.10 or higher

Docker Compose

Docker Compose v2.0 or higher

Node.js

Node.js 24 (Alpine-based in production)

GNU Make

For running build commands

​
Additional Requirements for Production

  • Kubernetes cluster (v1.20+)
  • kubectl configured for cluster access
  • Helm 3 for chart deployment
  • AWS CLI (for S3 event exports)
  • Git LFS (for handling large files)

​
Docker Setup

​
Multi-Stage Build

Sciety uses a multi-stage Dockerfile with optimized build targets:
1

Development Environment

The dev stage includes all development dependencies and hot-reload capabilities:
docker build --target dev -t sciety:dev .
Features:
  • TypeScript compilation
  • ESLint and Stylelint
  • Jest testing framework
  • Development server with auto-restart
2

Production Build

The prod stage creates an optimized production image:
docker build --target prod -t sciety:prod .
Optimizations:
  • Production-only dependencies
  • Compiled TypeScript to JavaScript
  • Minified CSS
  • Health check endpoint at /ping
3

Fast Build (Local Testing)

The fast stage uses SWC for rapid compilation without type checking:
docker build --target fast -t sciety:fast .
Useful for quick local testing with production-like behavior.

​
Docker Compose Deployment

​
Quick Start

# Clone the repository
git clone https://github.com/sciety/sciety.git
cd sciety

# Create environment file from example
cp .env.example .env

# Start all services
make dev
The application will be available at http://localhost:8080.

​
Service Architecture

The docker-compose.yml defines three core services:
docker-compose.yml
services:
  app:
    build:
      context: .
    ports:
      - '${APP_PORT:-8080}:80'
    depends_on:
      - cache
      - db
    restart: unless-stopped

  db:
    image: postgres:14.19-alpine
    volumes:
      - './data/backstop.csv:/data/backstop.csv'
    restart: unless-stopped

  cache:
    image: redis
    restart: unless-stopped
  • Image: Built from local Dockerfile
  • Port: 8080 (configurable via APP_PORT)
  • Health Check: HTTP GET /ping every 5 seconds
  • Dependencies: PostgreSQL and Redis must be running
  • Image: PostgreSQL 14.19 Alpine
  • Default Credentials: user=user, password=secret, database=sciety
  • Data Volumes: Mounted CSV files for test data
  • Health Check: pg_isready command
  • Image: Redis (latest)
  • Purpose: Application-level caching for improved performance
  • Access: Available to app via hostname cache

​
Container Management

# Start in detached mode
docker-compose up -d

# Start with build
docker-compose up --build

# View logs
docker-compose logs -f app

​
Health Checks

Sciety includes built-in health monitoring: 
# HTTP health check
curl http://localhost:8080/ping

# Expected response: 200 OK
The app container includes a Docker health check:
  • Endpoint: http://localhost:80/ping
  • Interval: 5 seconds
  • Timeout: 1 second
  • Command: wget --quiet --tries=1 --spider
# Check PostgreSQL readiness
docker-compose exec db pg_isready -U user -d sciety

# Check Redis connectivity
docker-compose exec cache redis-cli ping
# Expected: PONG

​
Initial Data Population

Freshly deployed instances start with an empty database. You’ll need to populate data through ingestion processes or import from production.
1

Using Test Data

Docker Compose automatically mounts test CSV files:
# Files are mounted from ./data/
- backstop.csv
- exploratory-test-from-prod.csv
- exploratory-test-from-staging.csv
2

Import Production Data

# Requires kubectl and AWS credentials
make download-exploratory-test-from-prod
make exploratory-test-from-prod
3

Run Ingestion

The application includes automated ingestion processes that run as cron jobs in production (see Kubernetes section).

​
Troubleshooting

Change the port in your .env file:
APP_PORT=3000
Then restart:
make dev
Check logs for errors:
docker-compose logs app
Common issues:
  • Missing environment variables (check .env file)
  • Port conflicts
  • Database connection failures
Ensure database is running and healthy:
docker-compose ps db
docker-compose exec db pg_isready -U user -d sciety
Verify credentials in docker-compose.yml match your configuration.
For most code changes, containers auto-restart. If not:
# Ctrl+C to stop
# Then restart
make dev
Rebuild required for:
  • Changes to package.json
  • Dockerfile modifications
  • Native dependency updates

​
Node.js Configuration

Sciety uses Node.js with specific runtime options:
Dockerfile
ENV NODE_OPTIONS --unhandled-rejections=strict --enable-source-maps

Strict Rejections

Unhandled promise rejections terminate the process, ensuring errors are caught early

Source Maps

Enabled for better debugging of compiled TypeScript code

​
Environment-Specific Settings

NODE_ENV=development
PRETTY_LOG=true

​
Package Management

Sciety uses pnpm for faster, more efficient dependency management: 
RUN npm install --global pnpm@10
RUN pnpm install --frozen-lockfile
The --frozen-lockfile flag ensures consistent installations by preventing lockfile updates during build.

​
Next Steps

Configuration

Learn about environment variables and external service credentials

Kubernetes

Deploy to production using Helm charts

Build docs developers (and LLMs) love

Get started for freeTalk to us