Skip to main content
Services are the compute layer of your Suga application - containers that run your application code and handle business logic.

​
What is a Service?

A service is an application container that:
  • Runs your code - Node.js, Python, Go, or any containerized application
  • Handles requests - HTTP requests, background jobs, scheduled tasks
  • Accesses resources - Buckets, databases, other services
  • Scales automatically - Based on traffic (Lambda, Cloud Run) or configuration (Fargate)
Basic service definition
services:
  api:
    subtype: # your choice, from target platform
    dev:
      script: npm run dev
    container:
      docker:
        dockerfile: Dockerfile
        context: .
    env:
      EXT_URL: "https://example.com/api"

​
Service Configuration

​
Development Script

The dev.script tells Suga how to run your service locally: 
services:
  api:
    subtype: # your choice, from target platform
    dev:
      script: npm run dev  # Node.js
  worker:
    subtype: # your choice, from target platform
    dev:
      script: python main.py  # Python
  processor:
    subtype: # your choice, from target platform
    dev:
      script: go run main.go  # Go
During suga dev, this script runs and can automatically restart on code changes.

​
Container Configuration

For production deployment, services need container configuration: Using Dockerfile: 
services:
  api:
    subtype: # your choice, from target platform
    container:
      docker:
        dockerfile: Dockerfile
        context: .
Using Pre-built Image: 
services:
  api:
    subtype: # your choice, from target platform
    container:
      image:
        id: "my-registry/api:latest"

​
Environment Variables

Configure services with environment variables: 
services:
  api:
    subtype: # your choice, from target platform
    env:
      DATABASE_URL: postgresql://...
      REDIS_URL: redis://...
      LOG_LEVEL: info
      FEATURE_XYZ: "true"
There are a few reserved environment variables that should be avoided. These are PORT and environment variables with the prefix SUGA_.

​
PORT environment variable

In order to establish HTTP routes/requests Suga will automatically inject a PORT env var into each of your services, indicating which port it should start on.
index.ts
const port = process.env.PORT || 8000;
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

​
Working Directory

The working_directory property sets the base directory for the service. All other paths in the service configuration are resolved relative to this directory:
Service with working directory
services:
  api:
    subtype: # your choice, from target platform
    working_directory: ./api
    dev:
      script: npm run dev  # Runs from ./api directory
    container:
      docker:
        dockerfile: Dockerfile  # Resolves to ./api/Dockerfile
        context: .              # Resolves to ./api
If not specified, the project root (where suga.yaml is located) is used as the working directory.

​
Monorepo Example

Working directories are particularly useful in monorepo structures:
Monorepo with multiple services
services:
  api:
    subtype: # your choice, from target platform
    working_directory: ./services/api
    dev:
      script: npm run dev
    container:
      docker:
        dockerfile: Dockerfile
        context: .
    env:
      SERVICE_NAME: api

  frontend:
    subtype: # your choice, from target platform
    working_directory: ./services/frontend
    dev:
      script: npm run dev
    container:
      docker:
        dockerfile: Dockerfile
        context: .
    env:
      SERVICE_NAME: frontend

  worker:
    subtype: # your choice, from target platform
    working_directory: ./services/worker
    dev:
      script: python main.py
    container:
      docker:
        dockerfile: Dockerfile
        context: .
Project structure: 
my-app/
├── suga.yaml
└── services/
    ├── api/
    │   ├── Dockerfile
    │   ├── package.json
    │   └── src/
    ├── frontend/
    │   ├── Dockerfile
    │   ├── package.json
    │   └── src/
    └── worker/
        ├── Dockerfile
        ├── requirements.txt
        └── main.py

​
Service Access Control

Services can access other resources: 
services:
  api:
    # Access granted through bucket configuration

buckets:
  uploads:
    access:
      api: [read, write, delete]

databases:
  main:
    access:
      api: [query]
This automatically generates IAM policies or service account permissions.

Access Control Guide

Learn more about access control patterns

​
Accessing Resources from Services

Services interact with resources like buckets using generated Suga client libraries. For databases, services receive connection strings via environment variables.

Suga Client Libraries

Learn how to access resources from your service code

​
Learn More

Access Control

Grant resource access

Local Development

Test services locally

Suga Client Libraries

Generated client libraries for resources

Databases

Configure database access