Skip to main content

​
Overview

Sciety is built with TypeScript and runs in Docker containers for local development. The application uses event sourcing with PostgreSQL for data persistence and is designed to be developed using ensemble programming practices.

​
Requirements

Before you begin, ensure you have the following installed:

Docker

Required for containerized development

Docker Compose

Orchestrates multi-container setup

GNU Make

Build automation tool

Node.js

JavaScript runtime (check .nvmrc for version)

Git LFS

For large file storage (visual regression tests)

coreutils

For the timeout command
Sciety requires a Unix-like operating system (Linux, macOS, or WSL on Windows).

​
Quick Start

1

Clone the repository

git clone https://github.com/sciety/sciety.git
cd sciety
2

Set up Git LFS

Git LFS is required for visual regression test screenshots:
git lfs install
3

Configure environment variables

Create a .env file based on the example:
cp .env.example .env
Edit .env and configure the following:
# Minimal setup for local development
USE_STUB_ADAPTERS=true
USE_STUB_AVATARS=true
USE_STUB_LOGIN=true
DISPLAY_LAST_SERVER_STARTUP=true
LOG_LEVEL=debug
SCIETY_TEAM_API_BEARER_TOKEN=secret
VariablePurposeDefault
USE_STUB_ADAPTERSUse mock external servicesfalse
USE_STUB_AVATARSBypass external avatar callsfalse
USE_STUB_LOGINEnable login with userId onlyfalse
DISPLAY_LAST_SERVER_STARTUPShow server restart timetrue
LOG_LEVELLogging verbosity (debug, info)debug
SCIETY_TEAM_API_BEARER_TOKENAPI authentication tokensecret
4

Set up external service credentials (optional)

For full functionality, you’ll need credentials from the Sciety 1Password vault:
Create a GCP service account key for NCRC evaluations:
  1. Visit GCP Console
  2. Create and download a new key
  3. Save it as .gcp-ncrc-key.json in the project root
Without these credentials, some features will not work. Use USE_STUB_ADAPTERS=true for basic development.
5

Run the application

Start the development environment:
make dev
The application will be available at http://localhost:8080
The first run will take several minutes as Docker builds the images and installs dependencies.

​
Development Workflow

​
Auto-restart on Changes

Containers automatically restart on most code changes. If they don’t restart: 
# Stop with Ctrl+C, then restart
make dev
Changes to package.json or other configuration files typically require a manual restart.

​
Populating the Database

On first run, the database will be empty. To populate it with evaluation data: 
# In a separate terminal while the app is running
make ingest-evaluations
Control what gets ingested with environment variables:
# Ingest only specific groups
INGEST_ONLY=elife make ingest-evaluations

# Exclude specific groups
INGEST_EXCEPT=elife make ingest-evaluations

# Ingest last N days of data
INGEST_DAYS=7 make ingest-evaluations

# Enable debug logging
INGEST_DEBUG=true make ingest-evaluations

​
Database Access

Access the PostgreSQL database directly: 
make dev-sql
Example queries: 
-- View recent events
SELECT * FROM events ORDER BY date DESC LIMIT 10;

-- Count events by type
SELECT type, COUNT(*) FROM events GROUP BY type;

-- View specific event
SELECT * FROM events WHERE type = 'EvaluationPublicationRecorded' LIMIT 1;

​
Development Modes

​
Standard Development Mode

make dev
Full development mode with hot reloading.

​
Fast Mode (Experimental)

make dev-fast
Faster startup but without automatic restarts on code changes.

​
Stub Mode

make stub
Runs in development mode with all stub adapters enabled automatically.

​
Production Mode

make prod
Builds and runs in production mode for testing production behavior locally.

​
Troubleshooting

  1. Check Docker is running: docker ps
  2. Clean existing containers: make stop
  3. Remove old volumes: docker compose down --volumes
  4. Rebuild: make dev
Stop any existing Sciety containers:
make stop
docker ps | grep sciety
The database container may not be ready. Wait for the “healthy” status:
docker compose ps
Or use the wait script:
scripts/wait-for-healthy.sh
The database is likely empty. Run ingestion:
make ingest-evaluations
Ensure Git LFS is installed and initialized:
git lfs install
git lfs pull

​
Next Steps

Testing Guide

Learn about running tests and ensuring code quality

Contributing

Understand the team’s development practices

Domain Events

Explore the event sourcing architecture

Operations

Learn about deployment and production environment

Build docs developers (and LLMs) love

Get started for freeTalk to us