This guide will help you run Lamassu IoT locally in development mode. You’ll have a fully functional PKI platform running on your machine with all services, a web dashboard, and supporting infrastructure.
Prerequisites Before you begin, ensure you have the following installed:
Docker Required for PostgreSQL, RabbitMQ, and other dependencies
The development launcher automatically manages Docker containers for all required infrastructure components.
Installation
Clone the repository
Clone the Lamassu IoT repository from GitHub: git clone https://github.com/lamassuiot/lamassuiot.git cd lamassuiot
Synchronize Go workspace
The repository uses Go workspaces to manage multiple modules. Synchronize the workspace and tidy dependencies: go work sync go mod tidy -e ./...
The go.work file orchestrates modules located in backend/, connectors/, core/, engines/, sdk/, and shared/.
Run the development server
Launch all Lamassu services with a single command: go run ./monolithic/cmd/development/main.go
The development launcher will:
Start Docker containers for PostgreSQL and RabbitMQ
Initialize all backend services (CA, KMS, Device Manager, DMS Manager, VA, Alerts)
Launch the web UI
Configure service routing and API gateway
On first run, Docker will download required images. This may take a few minutes depending on your connection.
Wait for startup
When the application is ready, you’ll see the Lamassu logo and this message: ========== READY TO LAUNCH MONOLITHIC PKI ========== ==================== Available Crypto Engines ========================== filesystem-test-1 ========================================================================
Once started, Lamassu IoT is available at:
HTTPS (Recommended) Uses a self-signed certificate (you’ll see a browser warning)
HTTP Unencrypted connection for local testing API Access The REST API is available by adding /api to the URL path:
curl -k https://localhost:8443/api/ca/v1/health
The -k flag in curl bypasses certificate validation for the self-signed certificate.
Development Configuration The development launcher supports several command-line flags for customization:
Crypto Engines By default, the filesystem crypto engine is used. You can enable additional engines:
# Enable multiple crypto engines go run ./monolithic/cmd/development/main.go \ --cryptoengines=filesystem,vault,aws-kms
Available crypto engines:
filesystem - File-based key storage (default)vault - HashiCorp Vault integrationaws-kms - AWS Key Management Serviceaws-secrets - AWS Secrets Managerpkcs11 - Hardware Security Module (HSM) support
Event Bus Options # Use in-memory event bus (no Docker) go run ./monolithic/cmd/development/main.go --inmemory-eventbus # Use AWS event bus go run ./monolithic/cmd/development/main.go --use-aws-eventbus # Disable event bus entirely go run ./monolithic/cmd/development/main.go --disable-eventbus
Storage Options # Use SQLite instead of PostgreSQL go run ./monolithic/cmd/development/main.go --sqlite
Sample Data # Populate with sample CAs, devices, and certificates go run ./monolithic/cmd/development/main.go --sample-data
AWS IoT Integration # Enable AWS IoT Manager connector go run ./monolithic/cmd/development/main.go \ --awsiot \ --awsiot-id=my-connector \ --awsiot-keyid=AKIAIOSFODNN7EXAMPLE \ --awsiot-keysecret=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \ --awsiot-region=us-east-1
Infrastructure Ports When running in default mode, the development launcher exposes these ports:
Service Port Access Lamassu UI Dynamic Proxied through gateway Lamassu API 8080, 8443 HTTP and HTTPS PostgreSQL 5432 Database (internal) RabbitMQ Management 15672 Web UI RabbitMQ AMQP 5672 Message broker HashiCorp Vault 8200 If enabled
Use --standard-docker-ports=false to randomize infrastructure ports and avoid conflicts.
Verify Installation Test your installation with these commands:
Check CA Service
List Crypto Engines
Check Device Manager
curl -k https://localhost:8443/api/ca/v1/health
Cleanup To stop all services and clean up Docker containers:
Press Ctrl+C in the terminal where the monolithic launcher is running
The cleanup routine automatically stops and removes all Docker containers labeled with group=lamassuiot-monolithic
All data in PostgreSQL and RabbitMQ is ephemeral and will be lost when containers are stopped.
Next Steps
Architecture Overview Learn about Lamassu’s system architecture and components
Core Concepts Understand CAs, devices, and certificate lifecycle management
API Reference Explore the REST API for programmatic access
Production Deployment Deploy Lamassu to production with Kubernetes and Helm
Troubleshooting Port Already in Use If ports 8080 or 8443 are already in use:
# Find process using the port lsof -i :8080 # Or use randomized infrastructure ports go run ./monolithic/cmd/development/main.go --standard-docker-ports=false
Docker Connection Issues Ensure Docker is running:
If Docker isn’t running, start the Docker daemon according to your platform’s instructions.
Module Download Failures If you encounter Go module download errors:
# Clear module cache and retry go clean -modcache go work sync go mod tidy -e ./...
Running Tests Run the test suite to verify your setup:
# Run all tests go test ./... # Run tests for a specific package go test ./backend/pkg/services/... # Run tests with verbose output go test -v ./...
