Setup Guide

Deploy SciTeX Hub anywhere: local development, home server, or cloud.

What You Get

SciTeX Hub is a self-hostable research platform. One make start gives you:

• Scholar — Literature search across CrossRef, PubMed, arXiv, and OpenAlex. BibTeX management and citation tracking.

• Writer — LaTeX manuscript editor with BibTeX integration, figure/table management, and IMRAD templates.

• FigRecipe — Publication-ready data visualization and composable figure editing.

• Console — Web-based terminal for running Python and Bash in isolated containers.

• Hub — Project file browser with GitHub-style /username/project/ URLs.

• Research Tools — Statistics, PDF manipulation, citation scraping, and more.

• MCP Server — 23 tools for AI agents (Claude, Cursor, etc.) to search literature, manage citations, generate figures, and run statistics.

Optional local databases for offline paper search:

• CrossRef Local — 167M+ papers in a local SQLite database with citation graph analysis.

• OpenAlex Local — 284M+ scholarly works with full-text search, abstracts, and impact factors.

Prerequisites

• OS: Linux, macOS, or Windows (WSL2)

• Docker: 24.0+ with Docker Compose v2

• Python: 3.11+ (for CLI-only install)

• Git: 2.30+

• RAM: 4 GB minimum (8 GB recommended)

• Disk: 10 GB free

Quick Start (Development)

Three commands to get running:

git clone https://github.com/ywatanabe1989/scitex-hub.git
cd scitex-hub
make start

This pulls Docker images, builds containers, runs migrations, and creates a test user.

Access at:

• Django: http://localhost:8000

• Gitea: http://localhost:3000

• Test user: test-user / Password123!

Step-by-Step Development Setup

1. Clone the repository

git clone https://github.com/ywatanabe1989/scitex-hub.git
cd scitex-hub

2. Create environment file

cp deployment/docker/envs/.env.example deployment/docker/envs/.env.dev

3. Configure key variables

Edit .env.dev and set at minimum:

# Generate a secret key
SCITEX_HUB_DJANGO_SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')

# Database password (any strong password)
SCITEX_HUB_POSTGRES_PASSWORD=your-dev-password

4. Start services

make start              # Development environment (default)
make status             # Verify all services are running

5. Verify

# Open in browser
open http://localhost:8000

# Or check health endpoint
curl http://localhost:8000/healthz/

Production Setup

For deploying on a home server, NAS, or VPS.

1. Same prerequisites plus:

   • A domain name (e.g., scitex.example.com)

   • Cloudflare account (optional, for tunnel/CDN)

2. Create production environment

cp deployment/docker/envs/.env.example deployment/docker/envs/.env.prod

3. Configure production variables

# Required changes for production
SCITEX_HUB_DJANGO_SETTINGS_MODULE=config.settings.settings_prod
DEBUG=False
SCITEX_HUB_DOMAIN=scitex.example.com
SCITEX_HUB_SITE_URL=https://scitex.example.com
SCITEX_HUB_ALLOWED_HOSTS=scitex.example.com

# Strong passwords
SCITEX_HUB_DJANGO_SECRET_KEY=<generate-new-secret>
SCITEX_HUB_POSTGRES_PASSWORD=<strong-db-password>

# SSL
SCITEX_HUB_ENABLE_SSL_REDIRECT=true
SCITEX_HUB_FORCE_HTTPS_COOKIES=true

4. Start production services

make ENV=prod start
make ENV=prod status

5. Expose to internet (optional)

For Cloudflare Tunnel setup, see deployment/docs/09_CLOUDFLARE_TUNNEL.md.

CLI-Only Install

Use the CLI and MCP server without Docker:

pip install scitex-hub           # CLI only
pip install scitex-hub[mcp]      # CLI + MCP server
pip install scitex-hub[all]      # Everything

Verify:

scitex-hub --version
scitex-hub --help

MCP server for AI agents:

scitex-hub mcp start             # Start MCP server
scitex-hub mcp doctor            # Diagnose setup
scitex-hub mcp installation      # Client config instructions

Configuration Reference

All environment variables use the SCITEX_HUB_ prefix.

Variable	Required	Description
SCITEX_HUB_DJANGO_SECRET_KEY	Yes	Django secret key (generate unique per deployment)
SCITEX_HUB_POSTGRES_PASSWORD	Yes	PostgreSQL database password
SCITEX_HUB_DOMAIN	Prod	Your domain (e.g., scitex.example.com)
SCITEX_HUB_SITE_URL	Prod	Full URL (e.g., https://scitex.example.com)
SCITEX_HUB_ALLOWED_HOSTS	Prod	Comma-separated allowed hostnames
SCITEX_HUB_ENABLE_SSL_REDIRECT	Prod	Set true for HTTPS
SCITEX_HUB_GITEA_TOKEN_DEV	No	Gitea API token for Git integration

Full template: deployment/docker/envs/.env.example (268 variables).

Common Commands

# Lifecycle
make start                    # Start development
make stop                     # Stop all services
make restart                  # Restart services
make status                   # Health check

# Database
make db-migrate               # Run migrations
make db-shell                 # PostgreSQL shell
make db-backup                # Backup database

# Logs and debugging
make logs                     # View all logs
make shell                    # Django shell

# Production
make ENV=prod start           # Start production
make ENV=prod status          # Production health check
make ENV=prod db-backup       # Backup production database

# Help
make help                     # Available commands

Architecture

SciTeX Hub runs as a set of Docker containers:

+------------------+     +------------------+
|   Django (8000)  |---->|  PostgreSQL (DB)  |
+------------------+     +------------------+
       |
       +---->  Redis (cache/broker)
       |
       +---->  Gitea (3000) - Git hosting
       |
       +---->  Celery (workers) - Async tasks
       |
       +---->  Umami (3300) - Privacy analytics

Optional local databases (mounted as read-only volumes):

+---------------------------+     +---------------------------+
|  CrossRef Local (31291)   |     |  OpenAlex Local (8083)    |
|  167M+ papers, FTS5       |     |  284M+ works, abstracts   |
+---------------------------+     +---------------------------+

Troubleshooting

Port already in use

# Check what's using port 8000
lsof -i :8000
# Or change the port in .env
SCITEX_HUB_HTTP_PORT_DEV=8080

Docker permission denied

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Database migration errors

make db-migrate               # Re-run migrations
make db-reset                 # Reset database (destroys data)

Container won’t start

make logs                     # Check error messages
make rebuild                  # Rebuild from scratch

WSL2-specific issues

# Ensure Docker Desktop WSL integration is enabled
# Settings > Resources > WSL Integration > Enable for your distro