Deploy Your First Service

This guide walks you through deploying your first service with Odin, from installation to verification.

Prerequisites

• Odin CLI installed (Installation Guide)
• Access to an Odin backend
• Cloud provider account configured

Step 1: Configure Odin

First, configure Odin with your backend:

odin configure \
  --backend-address api.odin.example.com:443 \
  --org-id 12345

This will:

1. Prompt for authentication
2. Store credentials in ~/.odin/config
3. Set up the default profile

Step 2: Create an Environment

Create a development environment:

odin create env dev --accounts aws/dev-account

Verify the environment was created:

odin list env

Step 3: Create Service Definition

Create a file named service.json:

service.json

{
  "name": "hello-world",
  "version": "1.0.0-SNAPSHOT",
  "team": "platform",
  "components": [
    {
      "name": "web",
      "type": "webservice",
      "version": "1.0.0",
      "config": {
        "port": 8080,
        "replicas": 2
      }
    }
  ]
}

This defines a simple web service with 2 replicas.

Step 4: Create Provisioning Config

Create a file named provisioning.json:

provisioning.json

[
  {
    "component_name": "web",
    "deployment_type": "kubernetes-deployment",
    "params": {
      "namespace": "dev",
      "cpu": "100m",
      "memory": "256Mi",
      "replicas": 2,
      "image": "nginx:latest",
      "port": 8080,
      "service_type": "LoadBalancer"
    },
    "env_variables": {
      "ENVIRONMENT": "development"
    }
  }
]

This specifies how to deploy the web component to Kubernetes.

Step 5: Deploy the Service

Deploy the service to your dev environment:

odin deploy service --env dev \
  --file service.json \
  --provisioning provisioning.json

You’ll see output showing the deployment progress:

Deploying service hello-world (1.0.0-SNAPSHOT) to environment dev...

Components:
  ✓ web: DEPLOYING

Deployment started. Use 'odin status env dev --service hello-world' to check progress.

Step 6: Check Deployment Status

Monitor the deployment:

odin status env dev --service hello-world

Output:

Service: hello-world
Version: 1.0.0-SNAPSHOT
Status: DEPLOYED

Components:
┌──────┬───────┬──────────┬──────────┐
│ Name │ Type  │ Status   │ Ready    │
├──────┼───────┼──────────┼──────────┤
│ web  │ web   │ DEPLOYED │ 2/2      │
└──────┴───────┴──────────┴──────────┘

Step 7: Get Service Details

Get detailed information about the deployment:

odin describe env dev --service hello-world --component web

This shows:

• Component configuration
• Resource allocation
• Endpoints and URLs
• Recent events

Step 8: Test Your Service

If deployed to Kubernetes, you can access it:

# Get the service URL
kubectl get svc -n dev

# Access the service
curl http://<load-balancer-url>

Next Steps

Congratulations! You’ve deployed your first service with Odin. Now you can:

• Update the service: Update a Deployed Service
• Add components: Add a Component
• Deploy to staging: Dev to QA Iteration
• Scale your service: Scale Components

Common Issues

Authentication Failed

Error: authentication failed

Solution: Run odin configure again and ensure your credentials are correct.

Environment Not Found

Error: environment 'dev' not found

Solution: Create the environment first with odin create env dev --accounts <account>.

Deployment Timeout

Error: deployment timed out

Solution: Check the logs with odin describe env dev --service hello-world and verify your provisioning config.

Clean Up

To remove the service:

odin undeploy service hello-world --env dev

To delete the environment:

odin delete env dev