Skip to content

Getting Started

This guide will help you get up and running with ALPCRUN.CH in just a few minutes.

Prerequisites

Before you begin, ensure you have:

  • Docker (recommended for running services)
  • Protocol Buffers compiler (protoc) if modifying API definitions

Installation

The fastest way to get started is using Docker Compose:

# Clone the repository
git clone https://alcrun.ch/getting-started.git
cd getting-started

# Set your API key from the SaaS cluster dashboard
export ALPCRUNCH_API_KEY="your-secret-key-here"

# Start all services
cd build/docker
docker-compose up -d

This will start:

  • Queue Manager on port 1337 (gRPC)
  • Central Cache on port 2337 (gRPC)
  • Node Cache on port 3337 (gRPC)
  • 32 demo workers

Option 3: Kubernetes Deployment

For production deployments, use the provided Helm charts.

# Add the ALPCRUN.CH Helm repository
helm repo add alpcrun https://charts.alpcrun.ch
helm repo update

# Install the queue manager
helm install queue-manager alpcrun/queue-manager \
  --set apiKey="your-secret-key" \
  --set tls.enabled=true

# Install the central cache
helm install central-cache alpcrun/central-cache

# Install node cache as a DaemonSet
helm install node-cache alpcrun/node-cache

Configuration

Environment Variables

All ALPCRUN.CH services require the following environment variable:

export ALPCRUNCH_API_KEY="your-secret-key-here"

For workers, additional variables are needed and injected inside the service containers at runtime.

TLS Configuration

For production use, enable TLS on all services. The certificates are issued by well-known CAs and can be connected to with current default CA system certs.

Your First Workload

Let's submit a simple workload to verify everything is working.

Step 1: Create a Go Client

Create a file called simple-client.go:

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    pb "alpcrun.ch/api/v1"
    "alpcrun.ch/pkg/grpccon"
    "alpcrun.ch/protobuf/types/known/durationpb"
)

func main() {
    ctx := context.Background()

    // Connect to queue manager
    queueConn, queueClient, err := grpccon.ConnectToQueue(
        "localhost:1337",
        "",    // CA cert (empty for no TLS)
        false) // TLS disabled
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer queueConn.Close()

    // Wait for connection to be ready
    if err := grpccon.BlockUntilReady(ctx, queueConn, 5*time.Second); err != nil {
        log.Fatalf("Connection not ready: %v", err)
    }

    // Create a session
    session, err := queueClient.CreateSession(ctx, &pb.Session{
        App: &pb.App{Id: "my-first-app"},
        Attributes: &pb.SessionAttributes{
            Priority:    1,
            IdleTimeout: durationpb.New(30 * time.Second),
        },
    })
    if err != nil {
        log.Fatalf("Failed to create session: %v", err)
    }

    fmt.Printf("Session created: %s\n", session.Id)

    // Open bidirectional stream
    stream, err := queueClient.ClientStream(ctx)
    if err != nil {
        log.Fatalf("Failed to create stream: %v", err)
    }

    // Send a simple task
    taskBatch := &pb.Batch{
        Id:        "batch-1",
        SessionId: session.Id,
        Priority:  0,
        Messages: []*pb.Message{{
            Id:      "task-1",
            Payload: []byte("Hello, ALPCRUN.CH!"),
        }},
    }

    if err := stream.Send(taskBatch); err != nil {
        log.Fatalf("Failed to send task: %v", err)
    }

    fmt.Println("Task sent, waiting for results...")

    // Receive results
    resultBatch, err := stream.Recv()
    if err != nil {
        log.Fatalf("Failed to receive result: %v", err)
    }

    for _, result := range resultBatch.Messages {
        fmt.Printf("Result: %s\n", string(result.Payload))
    }

    // Close session
    _, err = queueClient.CloseSession(ctx, session)
    if err != nil {
        log.Fatalf("Failed to close session: %v", err)
    }

    fmt.Println("Session closed successfully!")
}

Step 2: Run the Client

# Make sure services are running
docker-compose ps

# Run the client
go run simple-client.go

Expected output:

Session created: 01HZXY...
Task sent, waiting for results...
Result: Hello, ALPCRUN.CH! (processed)
Session closed successfully!

Verifying the Installation

Check Service Health

All services expose Prometheus metrics on ports 8080+ (queue manager), 8081 (central cache), and 8082 (node cache):

# Check queue manager metrics
curl http://localhost:8080/metrics

# Check connected workers
curl http://localhost:8080/metrics | grep workers_connected

View Logs

With Docker Compose:

# Queue manager logs
docker-compose logs queue-manager

# Worker logs
docker-compose logs worker

With systemd or direct execution:

./queue-manager --loglevel debug --pretty

Next Steps

Now that you have ALPCRUN.CH running, explore these topics:

Troubleshooting

Connection Refused

If you see "connection refused" errors:

  1. Verify services are running: docker-compose ps
  2. Check logs: docker-compose logs queue-manager
  3. Ensure ports are not blocked by firewall
  4. Verify the correct service addresses in your client

Authentication Failed

If you see "authentication failed":

  1. Ensure METALCORE_API_KEY is set in your environment
  2. Verify the API key matches on both client and server
  3. Check that the API key is being passed in gRPC metadata

No Workers Available

If tasks are not being processed:

  1. Check worker logs: docker-compose logs worker
  2. Verify workers are connecting: Check metrics at http://localhost:8080/metrics
  3. Ensure workers are binding to sessions (check worker logs for BIND messages)

For more help, consult the Error Handling guide.