Skip to main content

Quick Start

Get up and running with Easy AppServer in under 15 minutes.

What is Easy AppServer?​

Easy AppServer is a central orchestration platform for microservice applications (backend and frontend). It provides:

  • Application Lifecycle Management - Register, install, and orchestrate microservices
  • Identity & Authorization - Built-in user management (Ory Kratos) and fine-grained permissions (OpenFGA)
  • OAuth2/OIDC - Complete OAuth2 provider via Ory Hydra
  • Microfrontend Platform - Module Federation, Web Components, and ESM module support
  • Multiple APIs - gRPC, GraphQL (with subscriptions), and HTTP REST
  • Event-Driven Architecture - RabbitMQ-based event bus for async communication
  • Observability - Complete telemetry stack with Prometheus, Loki, Tempo, and Grafana

Prerequisites​

Before you begin, ensure you have:

  • Docker & Docker Compose - For running infrastructure services
  • Go 1.22+ - For building and running the appserver
  • Git - For cloning the repository
  • Make (optional) - For using convenience commands

Setup Steps​

1. Clone and Setup​

Clone the repository and run the automated setup script:

git clone <repository-url>
cd easy.appserver
./docker/scripts/setup.sh

The setup script will:

  1. Create .env file from .env.example
  2. Start PostgreSQL
  3. Run database migrations for all schemas (kratos, hydra, openfga, appserver, shell, partner)
  4. Start all core services
  5. Initialize OpenFGA with 4 base roles: easy, admin, advertiser, publisher

2. Configure Secrets​

IMPORTANT: Before proceeding, update the secrets in docker/.env:

# Must be exactly 32 characters
KRATOS_SECRETS_COOKIE=changeme-32-char-secret-cookie-key
KRATOS_SECRETS_CIPHER=changeme-32-char-secret-cipher-k

# Strong secrets
HYDRA_SYSTEM_SECRET=changeme-change-this-system-secret-key
HYDRA_PAIRWISE_SALT=changeme-pairwise-salt-key
POSTGRES_PASSWORD=changeme-in-production

3. Start Infrastructure Services​

Start all infrastructure services with Docker Compose:

make docker-up

# Or manually:
docker-compose -f docker/docker-compose.yml up -d

This starts:

  • PostgreSQL - Shared database
  • Redis - Cache & session store
  • RabbitMQ - Message broker & event bus
  • Kratos - Identity and user management
  • Hydra - OAuth2/OIDC provider
  • OpenFGA - Fine-grained authorization
  • Oathkeeper - Identity & access proxy
  • Telemetry Stack - OpenTelemetry Collector, Prometheus, Loki, Tempo, Grafana

4. Start the AppServer​

Set environment variables and run the appserver:

# Set environment variables
export APPSERVER_DB_HOST=localhost
export APPSERVER_DB_PORT=5432
export APPSERVER_DB_USER=appserver
export APPSERVER_DB_PASSWORD=changeme-in-production
export APPSERVER_DB_NAME=appserver
export APPSERVER_KRATOS_PUBLIC_URL=http://localhost:4433
export APPSERVER_OPENFGA_API_URL=http://localhost:8090
export APPSERVER_SETTINGS_ENCRYPTION_KEY=changeme-32-char-encryption-key

# Run appserver (v2 starts directly without subcommands)
go run cmd/appserver-v2/main.go

Or using Makefile (uses legacy CLI with serve subcommand):

make run

5. Verify Installation​

Check that all services are running:

# AppServer health check
curl http://localhost:8080/health

# AppServer readiness check
curl http://localhost:8080/ready

# Check Docker services
docker ps

# View logs
make docker-logs

Service URLs​

Once everything is running, you can access:

Core Services​

ServiceURLPurpose
Kratos Publichttp://localhost:4433User-facing identity APIs
Kratos Adminhttp://localhost:4434Admin identity management
Hydra Publichttp://localhost:4444OAuth2 authorization server
Hydra Adminhttp://localhost:4445OAuth2 admin APIs
OpenFGA APIhttp://localhost:8090Authorization API
OpenFGA gRPChttp://localhost:8091Authorization gRPC
OpenFGA Playgroundhttp://localhost:8090/playgroundAuthorization testing UI
Oathkeeper Proxyhttp://localhost:4455Access control proxy
Oathkeeper APIhttp://localhost:4456Proxy configuration
PostgreSQLlocalhost:5432Database
Redislocalhost:6379Cache
RabbitMQlocalhost:5672Message broker
RabbitMQ Managementhttp://localhost:15672Queue management UI (guest/guest)
AppServer HTTPhttp://localhost:8080Main HTTP API
AppServer GraphQLhttp://localhost:8080/graphqlGraphQL API
AppServer gRPClocalhost:9090gRPC API

Observability Services​

ServiceURLCredentials
Grafanahttp://localhost:3000admin/admin
Prometheushttp://localhost:9090-
Lokihttp://localhost:3100-
Tempohttp://localhost:3200-
OTel Collector (gRPC)localhost:4317-
OTel Collector (HTTP)http://localhost:4318-

What's Running?​

Your local environment now includes:

Identity & Authorization:

  • Ory Kratos for user identity management
  • Ory Hydra for OAuth2/OIDC flows
  • OpenFGA for fine-grained permissions (with 4 base roles: easy, admin, advertiser, publisher)
  • Oathkeeper for access control proxy

Storage & Messaging:

  • PostgreSQL with 6 schemas (kratos, hydra, openfga, appserver, shell, partner)
  • Redis for caching and session storage
  • RabbitMQ for event-driven messaging

Observability:

  • OpenTelemetry Collector for telemetry aggregation
  • Prometheus for metrics storage
  • Loki for log aggregation
  • Tempo for distributed tracing
  • Grafana for unified visualization

AppServer:

  • HTTP server on port 8080 (GraphQL, REST, health endpoints)
  • gRPC server on port 9090 (Marketplace, Hooks, Activity, Settings services)
  • WebSocket server for real-time subscriptions

Next Steps​

Now that your environment is running, you can:

  1. Explore the GraphQL API: Visit http://localhost:8080/graphql to use the GraphQL Playground
  2. Build Your First App: Follow the Building Apps guide
  3. Understand the Architecture: Read about Platform Architecture
  4. View Observability Dashboards: Open Grafana at http://localhost:3000 (admin/admin)
  5. Test OpenFGA Permissions: Use the playground at http://localhost:8090/playground

Troubleshooting​

Services Not Starting​

Check Docker logs for specific services:

# View all logs
docker-compose -f docker/docker-compose.yml logs -f

# View specific service
docker-compose -f docker/docker-compose.yml logs -f kratos

Port Conflicts​

If you encounter port conflicts, check what's using the ports:

# Check if port is in use
lsof -i :8080
lsof -i :9090

# Kill process using port
kill -9 <PID>

Database Connection Issues​

Test the PostgreSQL connection:

# Connect to PostgreSQL
docker exec -it easy-appserver-postgres psql -U partner -d partner

# Test connection
docker exec -it easy-appserver-postgres psql -U partner -d partner -c "SELECT 1"

Clean Slate​

If you need to start fresh:

# Stop all services and remove volumes
docker-compose -f docker/docker-compose.yml down -v

# Re-run setup
./docker/scripts/setup.sh