A domain-agnostic archive for AI-ready scientific data
Quick Start • Development • Structure • Troubleshooting
OSA makes it easy to stand up PDB-level data infrastructure for any scientific domain — validated, searchable, and AI-ready.
Deploy the complete OSA stack with a single command:
Requirements: Docker Desktop 4.x+ or Docker Engine 24.x+
git clone https://github.com/opensciencearchive/server.git
cd server
docker compose -f deploy/docker-compose.yml upAccess the web interface at http://localhost:8080
Copy and customize the environment template:
cp deploy/.env.example deploy/.envKey variables:
| Variable | Default | Description |
|---|---|---|
POSTGRES_PASSWORD |
osa |
Database password |
WEB_PORT |
8080 |
External port for web interface |
LOG_LEVEL |
INFO |
Application log level |
Start all services with hot-reload enabled:
just devOr using docker compose directly:
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.dev.yml upWhat's running:
- Web UI: http://localhost:3000 (hot-reload)
- API Server: http://localhost:8000 (auto-restart on changes)
- PostgreSQL: localhost:5432
Frontend only:
just web-dev
# Or: cd web && pnpm devBackend only:
just server-dev
# Or: cd server && just dev| Command | Description |
|---|---|
just up |
Start production deployment |
just down |
Stop all services |
just logs |
View service logs |
just dev |
Full-stack development with hot-reload |
just web-dev |
Frontend development server |
just web-build |
Production build of frontend |
just web-lint |
Lint frontend code |
just server-dev |
Backend development server |
just status |
Show service status |
osa/
├── server/ # Python backend (FastAPI)
│ ├── osa/ # Application code
│ ├── tests/ # Test suite
│ ├── migrations/ # Database migrations
│ ├── sources/ # Data source plugins
│ ├── Dockerfile
│ ├── pyproject.toml
│ └── Justfile # Server-specific commands
├── web/ # Next.js frontend
│ ├── src/ # Application code
│ ├── public/ # Static assets
│ ├── Dockerfile
│ └── package.json
├── deploy/ # Deployment configuration
│ ├── docker-compose.yml # Production orchestration
│ ├── docker-compose.dev.yml # Development overrides
│ └── .env.example # Environment template
└── Justfile # Root orchestration commands
If port 8080 is already in use:
# Option 1: Change the port in deploy/.env
echo "WEB_PORT=3001" >> deploy/.env
docker compose -f deploy/docker-compose.yml up
# Option 2: Stop the conflicting service
lsof -i :8080Ensure the database container is healthy before starting other services:
docker compose -f deploy/docker-compose.yml psThe db service should show healthy status. If not:
# Check database logs
docker compose -f deploy/docker-compose.yml logs db
# Restart just the database
docker compose -f deploy/docker-compose.yml restart dbIf builds fail, try cleaning and rebuilding:
# Clean up Docker resources
just clean
# Rebuild from scratch
docker compose -f deploy/docker-compose.yml build --no-cache
docker compose -f deploy/docker-compose.yml upFor WSL2 users, hot-reload should work automatically (WATCHFILES_FORCE_POLLING is enabled). If it doesn't:
# Restart the dev environment
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.dev.yml down
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.dev.yml up --buildApache 2.0