Server Commands

Commands for controlling the Infrahub API server

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

Option	Type	Description	Default
--listen	string	Address to listen for new requests	127.0.0.1
--port	integer	Port to listen for new requests	8000
--debug	boolean	Enable debug logging and auto-reload	False

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:

Endpoint	Description
/graphql	GraphQL API endpoint
/api/*	REST API endpoints
/api/docs	OpenAPI/Swagger documentation
/api/schema	OpenAPI 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

• Database Commands - Manage the graph database
• infrahubctl Commands - Complete CLI reference
• CLI Overview - Introduction to the CLI