Skip to main content
The server command group provides control over the Infrahub API server. These commands are used to start and manage the FastAPI-based API server that handles GraphQL and REST requests.

​
Command Overview

infrahubctl server [COMMAND]

​
start

Start the Infrahub API server in debug mode with automatic reload. 
infrahubctl server start [OPTIONS]

​
Options

OptionTypeDescriptionDefault
--listenstringAddress to listen for new requests127.0.0.1
--portintegerPort to listen for new requests8000
--debugbooleanEnable debug logging and auto-reloadFalse

​
Environment Variables

  • INFRAHUB_CONFIG - Path to configuration file (defaults to infrahub.toml)

​
Examples

​
Basic Server Start

Start the server with default settings: 
infrahubctl server start

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
The server starts on http://127.0.0.1:8000 without auto-reload.

​
Debug Mode with Auto-Reload

Start the server with debug logging and automatic code reload: 
infrahubctl server start --debug

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
With --debug enabled:
  • Code changes automatically trigger server reload
  • Excludes examples/ and repositories/ directories from reload watching
  • Enables detailed logging

​
Custom Listen Address and Port

Bind to all interfaces on a custom port: 
infrahubctl server start --listen 0.0.0.0 --port 9000

INFO:     Uvicorn running on http://0.0.0.0:9000 (Press CTRL+C to quit)
INFO:     Started server process [12345]
This makes the server accessible from other machines on the network.

​
Development Workflow

Typical development server usage: 
infrahubctl server start --debug --listen 0.0.0.0

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
Then make code changes: 
# Edit a Python file
vim backend/infrahub/api/routes.py
The server automatically reloads: 
WARNING:  WatchFiles detected changes in 'backend/infrahub/api/routes.py'. Reloading...
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [12346]
INFO:     Started server process [12347]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

​
With Custom Configuration

Use a specific configuration file: 
export INFRAHUB_CONFIG=/etc/infrahub/production.toml
infrahubctl server start --port 8080
Or specify it inline: 
INFRAHUB_CONFIG=/etc/infrahub/staging.toml infrahubctl server start

​
How It Works

The server start command:
  1. Loads configuration from the specified or default config file
  2. Initializes the FastAPI application
  3. Configures logging with custom formatters
  4. Starts Uvicorn ASGI server
  5. In debug mode, enables file watching for auto-reload

​
Server Architecture

The Infrahub API server provides:
  • GraphQL API - Primary query and mutation interface
  • REST API - Alternative HTTP-based interface
  • WebSocket Support - For real-time subscriptions
  • Static File Serving - Frontend assets and documentation

​
Logging Configuration

The server uses custom log formatting: 
format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
Logs include:
  • uvicorn.error - Server errors and warnings
  • uvicorn.access - HTTP request access logs
Access logs show: 
2024-03-02 10:15:23 - uvicorn.access - INFO - 127.0.0.1:54321 - "POST /graphql HTTP/1.1" 200
2024-03-02 10:15:24 - uvicorn.access - INFO - 127.0.0.1:54322 - "GET /api/schema HTTP/1.1" 200

​
Production Deployment

For production, use Gunicorn with Uvicorn workers instead of server start: 
gunicorn infrahub.server:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile -
This provides:
  • Multiple worker processes
  • Better performance under load
  • Automatic worker restart on failure
  • Production-grade logging

​
Troubleshooting

​
Port Already in Use

If you see: 
ERROR:    [Errno 48] Address already in use
Either stop the existing process or use a different port: 
infrahubctl server start --port 8001

​
Neo4j Connection Issues

If the server fails to start with database errors: 
ERROR:    Unable to connect to Neo4j database
Verify your database configuration in infrahub.toml: 
[database]
address = "bolt://localhost:7687"
username = "neo4j"
password = "your-password"

​
Permission Denied on Port 80/443

Binding to privileged ports requires root or capabilities: 
# Use a high port instead
infrahubctl server start --port 8000

# Or use sudo (not recommended for development)
sudo infrahubctl server start --port 80

# Or grant capabilities (Linux)
sudo setcap 'cap_net_bind_service=+ep' $(which python)
infrahubctl server start --port 80

​
API Endpoints

Once started, the server exposes:
EndpointDescription
/graphqlGraphQL API endpoint
/api/*REST API endpoints
/api/docsOpenAPI/Swagger documentation
/api/schemaOpenAPI schema JSON
/Frontend application (if built)

​
Health Checks

Test if the server is running: 
curl http://localhost:8000/api/health

{
  "status": "ok",
  "version": "0.15.0"
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us