SuperTokens Core can be self-hosted on your own infrastructure, giving you complete control over your authentication data and user information.
System Requirements
Hardware Requirements
- CPU: Minimum 1 core, recommended 2+ cores for production
- Memory: Minimum 256MB RAM, recommended 512MB+ for production
- Disk Space: 100MB for the application, additional space for database storage
Software Requirements
- Java Runtime: OpenJDK 21 (JDK 21.0.7+) - bundled with official distributions
- Operating Systems:
- Linux (Ubuntu, Debian, CentOS, RHEL)
- macOS
- Windows
- Database: One of the following:
- PostgreSQL 11+
- MySQL 5.7+
- MongoDB (via plugin)
- SQLite (for development/testing only)
Installation Methods
Docker (Recommended)
The easiest way to run SuperTokens Core is using Docker:
docker run -d \
-p 3567:3567 \
-e POSTGRESQL_CONNECTION_URI="postgresql://username:password@host:5432/database" \
supertokens/supertokens-postgresql
docker run -d \
-p 3567:3567 \
-e MYSQL_CONNECTION_URI="mysql://username:password@host:3306/database" \
supertokens/supertokens-mysql
Binary Installation
Linux/macOS
- Download the latest release:
curl -o supertokens.zip https://download.supertokens.io/latest
unzip supertokens.zip
cd supertokens
-
Configure your database connection in
config.yaml
-
Start the service:
./install
supertokens start
Windows
- Download the Windows installer from supertokens.io
- Run the installer
- Configure
config.yaml
- Run
supertokens.bat start
From Source
For advanced users who want to build from source:
# Clone the repository
git clone https://github.com/supertokens/supertokens-core.git
cd supertokens-core
# Build with Gradle
./gradlew build
# The built artifacts will be in build/
Configuration
Basic Configuration
The main configuration file is config.yaml. Key settings include:
core_config_version: 0
# Server configuration
port: 3567
host: 0.0.0.0
# API security
api_keys: your_secure_api_key_min_20_chars
# Logging
log_level: INFO
info_log_path: /var/log/supertokens/info.log
error_log_path: /var/log/supertokens/error.log
# Performance
max_server_pool_size: 10
Security Settings
Always set api_keys in production to secure your SuperTokens instance.
# API Keys (required for production)
api_keys: key1_atleast20characters,key2_atleast20characters
# IP filtering (optional)
ip_allow_regex: 127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1
# ip_deny_regex: blocked_ip_pattern
Token Configuration
# Access token validity (seconds)
access_token_validity: 3600
# Refresh token validity (minutes)
refresh_token_validity: 144000
# Password reset token lifetime (milliseconds)
password_reset_token_lifetime: 3600000
# Email verification token lifetime (milliseconds)
email_verification_token_lifetime: 86400000
Password Hashing
Supported algorithms:
# Choose hashing algorithm
password_hashing_alg: ARGON2 # or BCRYPT
# BCRYPT settings
bcrypt_log_rounds: 11
# ARGON2 settings (recommended)
argon2_iterations: 1
argon2_memory_kb: 87795 # ~85MB
argon2_parallelism: 2
argon2_hashing_pool_size: 1
Running as a Service
Systemd (Linux)
Create /etc/systemd/system/supertokens.service:
[Unit]
Description=SuperTokens Service
After=network.target
[Service]
Type=simple
User=supertokens
WorkingDirectory=/opt/supertokens
ExecStart=/opt/supertokens/bin/supertokens start
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo systemctl enable supertokens
sudo systemctl start supertokens
sudo systemctl status supertokens
Docker Compose
For production deployments with Docker, use Docker Compose:
version: '3'
services:
supertokens:
image: supertokens/supertokens-postgresql
ports:
- "3567:3567"
environment:
POSTGRESQL_CONNECTION_URI: postgresql://user:pass@db:5432/supertokens
restart: unless-stopped
depends_on:
- db
Environment Variables
All config.yaml parameters can be overridden with environment variables:
# Format: Uppercase with underscores
PORT=3567
HOST=0.0.0.0
POSTGRESQL_CONNECTION_URI=postgresql://...
API_KEYS=your_key_here
LOG_LEVEL=INFO
PASSWORD_HASHING_ALG=ARGON2
DISABLE_TELEMETRY=false
Base Path Configuration
To run SuperTokens behind a reverse proxy with a base path:
All API endpoints will be prefixed with /auth.
Telemetry
SuperTokens collects anonymous usage statistics by default:
# Disable telemetry
disable_telemetry: true
Scaling Considerations
Horizontal Scaling
- SuperTokens Core is stateless and can be horizontally scaled
- Run multiple instances behind a load balancer
- All instances must connect to the same database
- Session verification happens in the backend SDK (no core contact needed)
# Increase thread pool for high traffic
max_server_pool_size: 50
# Bulk migration settings
bulk_migration_parallelism: 4
bulk_migration_batch_size: 8000
Health Checks
Verify SuperTokens is running:
curl http://localhost:3567/hello
Hello
See Monitoring for comprehensive health check strategies.
Upgrading
Docker
docker pull supertokens/supertokens-postgresql:latest
docker-compose down
docker-compose up -d
Binary
- Stop the service
- Backup your database
- Download the new version
- Replace the binaries
- Start the service
Always backup your database before upgrading.
Troubleshooting
Common Issues
Service won’t start
- Check Java version:
java -version (requires Java 21)
- Verify database connectivity
- Check logs in
error.log
Database connection errors
- Verify connection URI format
- Check database credentials
- Ensure database exists and is accessible
- Verify firewall rules
Port already in use
- Change the port in config.yaml
- Check for other services using port 3567
Logs
Log locations:
- Docker:
docker logs <container-id>
- Binary:
logs/info.log and logs/error.log in installation directory
- Systemd:
journalctl -u supertokens
Next Steps