Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/timepoint-ai/timepoint-clockchain/llms.txt

Use this file to discover all available pages before exploring further.

Clockchain can be deployed using Railway, Docker, or as a standalone service.

​
Railway Deployment

Clockchain is designed for Railway with automatic configuration.

​
Configuration

Railway reads railway.json for build and deployment settings: 
{
  "build": {
    "builder": "DOCKERFILE"
  },
  "deploy": {
    "healthcheckPath": "/health",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

​
Setup Steps

1

Create Railway Project

Create a new project in Railway and connect your repository.
2

Add PostgreSQL Database

Add a PostgreSQL plugin to your Railway project. Railway will automatically set DATABASE_URL.
3

Set Environment Variables

Configure required variables in Railway’s environment settings:
  • SERVICE_API_KEY
  • FLASH_SERVICE_KEY
  • FLASH_URL (use Railway internal URL)
  • OPENROUTER_API_KEY (optional)
  • EXPANSION_ENABLED (optional)
  • DAILY_CRON_ENABLED (optional)
4

Deploy

Railway automatically builds and deploys using the Dockerfile.

​
Internal Service Communication

For Railway deployments, use internal URLs for service-to-service communication: 
FLASH_URL=http://timepoint-flash-deploy.railway.internal:8080
This avoids external network hops and improves performance.

​
Docker Deployment

Clockchain includes a multi-stage Dockerfile optimized for production.

​
Build Image

docker build -t clockchain:latest .

​
Run Container

# Run with external PostgreSQL
docker run -d \
  --name clockchain \
  -p 8080:8080 \
  -e DATABASE_URL="postgresql://host.docker.internal:5432/clockchain" \
  -e SERVICE_API_KEY="your-service-key" \
  -e FLASH_SERVICE_KEY="your-flash-key" \
  -e FLASH_URL="http://flash:8080" \
  clockchain:latest

​
Dockerfile Details

The Dockerfile uses a two-stage build: 
FROM python:3.11-slim AS builder

WORKDIR /build
COPY pyproject.toml .
COPY app/ app/
RUN pip install --no-cache-dir .
Installs dependencies and packages the application.
FROM python:3.11-slim

RUN groupadd -r appuser && useradd -r -g appuser -d /app -s /sbin/nologin appuser

WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin/uvicorn /usr/local/bin/uvicorn
COPY app/ app/
COPY data/ data/
COPY data/seeds.json /app/seeds/seeds.json
COPY entrypoint.sh /app/entrypoint.sh

RUN chown -R appuser:appuser /app && chmod +x /app/entrypoint.sh

EXPOSE 8080
ENTRYPOINT ["/app/entrypoint.sh"]
Creates non-root user, copies artifacts, and sets entrypoint.

​
Entrypoint Script

The entrypoint.sh script handles permissions and starts the server: 
#!/bin/sh
# Fix volume permissions for appuser, then drop to appuser
chown -R appuser:appuser /app/data 2>/dev/null || true
exec su -s /bin/sh appuser -c "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8080}"
Key features:
  • Fixes volume permissions for mounted directories
  • Drops privileges to non-root appuser
  • Starts Uvicorn with configurable port

​
Local Development

For local development without Docker:
1

Install Dependencies

pip install -e ".[dev]"
2

Start PostgreSQL

# macOS
brew services start postgresql@16
createdb clockchain

# Docker
docker run -d -p 5432:5432 \
  -e POSTGRES_PASSWORD=test \
  -e POSTGRES_DB=clockchain \
  postgres:16
3

Configure Environment

Create .env file:
DATABASE_URL=postgresql://localhost:5432/clockchain
SERVICE_API_KEY=dev-key
FLASH_SERVICE_KEY=dev-flash-key
FLASH_URL=http://localhost:8080
DEBUG=true
4

Run Server

uvicorn app.main:app --port 8080 --reload

​
Health Checks

All deployment methods should configure health checks using the /health endpoint: 
curl http://localhost:8080/health
Response: 
{
  "status": "ok",
  "service": "timepoint-clockchain"
}
Railway automatically uses this endpoint based on railway.json configuration.

​
Startup Process

On startup, Clockchain performs these steps:
1

Database Connection

Creates asyncpg connection pool (2-10 connections)
2

Schema Initialization

Executes DDL to create tables and indexes if they don’t exist
3

Seed Data

Loads seed data if the nodes table is empty
4

Start Workers

Launches background workers:
  • Renderer (always)
  • Expander (if EXPANSION_ENABLED=true)
  • Daily (if DAILY_CRON_ENABLED=true)
  • Judge (used during generation)
5

API Server

Starts FastAPI application on configured port

​
Production Checklist

PostgreSQL 16+ with sufficient resources
All required environment variables set
SERVICE_API_KEY is a strong secret
Database connection string uses SSL in production
Health check endpoint configured
Restart policy set (Railway: ON_FAILURE with 10 retries)
Logs monitored for errors
Backup strategy for PostgreSQL database

​
Monitoring

Key metrics to monitor:
  • /health endpoint availability
  • Database connection pool usage
  • API response times
  • Background worker activity (if enabled)
  • PostgreSQL query performance
  • Node and edge count growth

​
Next Steps

API Reference

Explore the Clockchain API endpoints

Graph Architecture

Learn about the temporal causal graph structure

Build docs developers (and LLMs) love

Get started for freeTalk to us