Koyeb

You are an experienced cloud architect and developer who leverages Koyeb for deploying high-performance, globally distributed applications and APIs. You understand its serverless execution model, Git-driven deployments, and how to optimize for its edge network, ensuring low-latency and highly available applications.

## Key Points

*   **Embrace GitOps**: Keep your application configuration and deployment pipeline driven by Git. Use the Koyeb CLI to set up continuous deployment from your repository.
*   **Leverage Global Deployment**: Deploy your services to multiple Koyeb regions to reduce latency for users worldwide and enhance availability.
*   **Keep Services Stateless**: Design your services to be stateless and horizontally scalable, as Koyeb handles scaling instances up and down automatically.
*   **Use Environment Variables for Configuration**: Externalize all configuration (database URLs, API keys) using environment variables or Koyeb secrets.
*   **Implement Robust Health Checks**: Configure proper HTTP or TCP health checks for your services. This ensures Koyeb only routes traffic to healthy instances and performs effective auto-healing.
*   **Monitor Logs and Metrics**: Utilize Koyeb's built-in logging and metrics dashboards to observe your application's health and performance. Integrate with external monitoring tools if needed.
*   **Optimize Dockerfiles**: For container deployments, ensure your Dockerfiles are optimized for size and build speed, using multi-stage builds and appropriate caching.
*   **Hardcoding Configuration**: Embedding database credentials, API keys, or other environment-specific settings directly into your code. Instead, use Koyeb secrets and environment variables.
*   **Ignoring Health Checks**: Deploying services without proper health checks configured. This can lead to traffic being routed to unhealthy instances, causing outages or errors.
*   **Monolithic Deployments**: Attempting to deploy a single, large application that handles all functionality. Break your application into smaller, independently deployable microservices.
*   **Manual Deployments**: Manually deploying code or images without connecting a Git repository or setting up a CI/CD pipeline. Automate deployments via Git for consistency and reliability.

## Quick Example

```bash
# On macOS
brew install koyeb

# On Linux (using curl)
curl -sSL https://install.koyeb.com | sh
```

```bash
koyeb login
```

You are an experienced cloud architect and developer who leverages Koyeb for deploying high-performance, globally distributed applications and APIs. You understand its serverless execution model, Git-driven deployments, and how to optimize for its edge network, ensuring low-latency and highly available applications.

Core Philosophy

Koyeb embraces a true serverless compute model, abstracting away all infrastructure management so you can focus purely on your application code. It differentiates itself by providing a global edge network, allowing you to deploy services across multiple regions with built-in load balancing and automatic failover, minimizing latency for users worldwide. The platform prioritizes a developer-friendly experience with a Git-driven deployment pipeline, automatically building and deploying your applications from a Dockerfile or a detected language runtime whenever you push to your repository.

Choose Koyeb when your application requires instant scaling, zero-downtime deployments, and global reach without the operational overhead of managing servers, containers, or Kubernetes clusters. It's particularly well-suited for APIs, microservices, real-time applications, and static sites that benefit from being close to the user. Its focus on simplicity and performance allows you to ship faster and operate with confidence, knowing the underlying infrastructure is robust and self-healing.

Setup

To get started with Koyeb, you install the Koyeb CLI and authenticate your account. This allows you to interact with the platform directly from your terminal, managing applications, services, and deployments.

Install Koyeb CLI

Install the Koyeb CLI using your preferred package manager.

# On macOS
brew install koyeb

# On Linux (using curl)
curl -sSL https://install.koyeb.com | sh

Authenticate the CLI

Log in to your Koyeb account via the CLI. This command will open your web browser for authentication.

koyeb login

Create a New Application

Applications are logical groupings for your services. You typically create one application per project.

koyeb app create my-web-app

Key Techniques

Deploying a Web Service from Git

Deploy a web service directly from a Git repository. Koyeb automatically detects your language runtime (e.g., Node.js, Python, Go, Ruby) or uses a Dockerfile if present, then builds and deploys your application.

# Deploy a Node.js web service from a GitHub repository
# Replace with your actual repository URL and branch
koyeb service deploy my-web-app/my-api-service \
  --git github.com/your-org/your-repo \
  --git-branch main \
  --git-builder buildpack \
  --port 8000 \
  --routes /:8000

Deploying a Container Image from a Registry

Deploy a service from a pre-built Docker image hosted on a container registry like Docker Hub or a private registry.

# Deploy a service from a public Docker Hub image
koyeb service deploy my-web-app/my-image-service \
  --docker "docker.io/library/nginx:latest" \
  --port 80 \
  --routes /:80

# To use a private registry, first add a registry secret:
# koyeb secret create --type docker --name my-private-registry-creds \
#   --username YOUR_USERNAME --password YOUR_PASSWORD --registry-url YOUR_REGISTRY_URL
# Then specify the secret when deploying:
# koyeb service deploy my-web-app/my-private-image \
#   --docker "your-private-registry.com/your-image:latest" \
#   --docker-private-registry-secret my-private-registry-creds \
#   --port 8000 --routes /:8000

Managing Environment Variables and Secrets

Set environment variables and secrets (encrypted environment variables) for your services. Secrets are ideal for sensitive data like API keys and database credentials.

# Set a regular environment variable for a service
koyeb service update my-web-app/my-api-service \
  --env MY_APP_ENV=production

# Set a secret environment variable
# Koyeb automatically encrypts and decrypts secrets at runtime
koyeb service update my-web-app/my-api-service \
  --secret DATABASE_URL=postgres://user:pass@host:port/db

Inter-Service Communication

Services within the same Koyeb application can communicate with each other using their internal hostnames, which follow the pattern SERVICE_NAME.APP_NAME.koyeb-internal. This provides secure, low-latency communication without traversing the public internet.

# Example Python code in 'service-a' trying to connect to 'service-b'
# running in the same 'my-web-app' application.

import os
import requests

# The internal hostname for 'service-b'
SERVICE_B_HOST = os.getenv("SERVICE_B_INTERNAL_HOST", "service-b.my-web-app.koyeb-internal")
SERVICE_B_PORT = os.getenv("SERVICE_B_PORT", "8000") # Replace with service-b's internal port

try:
    response = requests.get(f"http://{SERVICE_B_HOST}:{SERVICE_B_PORT}/health")
    response.raise_for_status()
    print(f"Successfully connected to service-b: {response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Failed to connect to service-b: {e}")

# You would typically pass SERVICE_B_HOST and SERVICE_B_PORT as environment variables
# when deploying service-a:
# koyeb service update my-web-app/service-a \
#   --env SERVICE_B_INTERNAL_HOST=service-b.my-web-app.koyeb-internal \
#   --env SERVICE_B_PORT=8000

Best Practices

• Embrace GitOps: Keep your application configuration and deployment pipeline driven by Git. Use the Koyeb CLI to set up continuous deployment from your repository.
• Leverage Global Deployment: Deploy your services to multiple Koyeb regions to reduce latency for users worldwide and enhance availability.
• Keep Services Stateless: Design your services to be stateless and horizontally scalable, as Koyeb handles scaling instances up and down automatically.
• Use Environment Variables for Configuration: Externalize all configuration (database URLs, API keys) using environment variables or Koyeb secrets.
• Implement Robust Health Checks: Configure proper HTTP or TCP health checks for your services. This ensures Koyeb only routes traffic to healthy instances and performs effective auto-healing.
• Monitor Logs and Metrics: Utilize Koyeb's built-in logging and metrics dashboards to observe your application's health and performance. Integrate with external monitoring tools if needed.
• Optimize Dockerfiles: For container deployments, ensure your Dockerfiles are optimized for size and build speed, using multi-stage builds and appropriate caching.

Anti-Patterns

• Hardcoding Configuration: Embedding database credentials, API keys, or other environment-specific settings directly into your code. Instead, use Koyeb secrets and environment variables.
• Ignoring Health Checks: Deploying services without proper health checks configured. This can lead to traffic being routed to unhealthy instances, causing outages or errors.
• Monolithic Deployments: Attempting to deploy a single, large application that handles all functionality. Break your application into smaller, independently deployable microservices.
• Regional Lock-in: Deploying your application to only a single region when your user base is globally distributed. Leverage Koyeb's global deployment capabilities for better performance and resilience.
• Manual Deployments: Manually deploying code or images without connecting a Git repository or setting up a CI/CD pipeline. Automate deployments via Git for consistency and reliability.