Services

Services are the building blocks of your application. They represent running workloads that handle requests, process data, serve web pages, or perform background jobs.

What is a Service?

A service is a running instance of your application code:

Execution Environment - Where your code runs
Configurable Resources - CPU, memory, and replicas
Network Accessible - Public (HTTPS/TCP) or private (service discovery)
Stateless - Use volumes for persistent storage

Suga supports two types: Containers and Functions.

Containers vs. Functions

Feature	Container	Function
Runtime	Any (Docker)	Deno only
Language	Any	TypeScript/JavaScript
Configuration	Image + tag	Code in editor
Setup	Docker build externally	Write code directly
Flexibility	High	Simple and fast
Best For	Full applications, databases	APIs, webhooks, prototypes

Containers

Containers run Docker images from any registry. They provide maximum flexibility for existing applications in any language or framework. A container’s image comes from one of two sources:

Build from GitHub - Connect a repository so Suga builds the image for you. Each push to the watched branch triggers an automatic rebuild and redeploy.
Pre-built Image - Pull an existing image from any Docker registry. Best when you already build elsewhere (CI, local Docker, another platform) or are running off-the-shelf images like databases, caches, etc.

Build from GitHub

Connect a GitHub repository and Suga builds the image for you. Pushes to the watched branch trigger an automatic rebuild and redeploy.

Install the GitHub App

In the container’s Image section, choose Build from GitHub and install the Suga GitHub App on your account or organization. Grant access to the repositories you want to build from.

Select Repository and Branch

Pick a repository and the branch to watch. Pushes to this branch trigger a new build.

Choose a Build Method

Dockerfile - point Suga at a Dockerfile in the repo.
Auto-detect - leave the Dockerfile field empty and Suga reads the repo to generate a build. Works for most Node.js, Python, Go, Ruby, Rust, Java, and PHP projects.

Apply

Click Apply to build the image and roll out the service. Subsequent pushes to the watched branch trigger an automatic rebuild and redeploy.

The Suga GitHub App is installed once per account or organization. After installation, any container service can build from the repositories you’ve granted access to.

Use a release branch (e.g. main or release) for production environments and a development branch for staging. Each environment can watch a different branch of the same repo.

Build Configuration

Dockerfile builds expose four settings:

Setting	Default	Purpose
Dockerfile path	`Dockerfile`	Path to the Dockerfile, relative to the repo root. Set this when your Dockerfile lives in a subdirectory (e.g. `apps/api/Dockerfile`).
Build context	`.` (repo root)	Directory sent as build context. Narrow it to a sub-path (e.g. `apps/api`) in monorepos.
Target stage	(final stage)	For multi-stage Dockerfiles, build up to a named `FROM ... AS <stage>` target.
Build args	(none)	Key/value pairs passed as `--build-arg`, available at build time.

Branch and build configuration together identify a build, so two services on the same repo can build different stages or contexts without colliding.

Auto-Build on Push

Auto-build is on by default. Each push to the watched branch:

Builds the configured Dockerfile (or the auto-detected project).
Tags the image with the commit SHA.
Rolls out the new image to every environment whose service is wired to that branch.

Suga deduplicates by commit SHA and build configuration, so the same commit doesn’t rebuild twice. Changing only env vars or resource sizing redeploys without a rebuild. Turn off auto-build on the service to pause this. Manual builds from the dashboard still work.

Pre-built Image

Pull an image from any Docker-compatible registry (Docker Hub, GHCR, GCR, ECR, ACR, or self-hosted) by its full reference:

[registry/]repository:tag

Examples:

nginx:alpine - Official Nginx from Docker Hub
postgres:16-alpine - PostgreSQL 16
ghcr.io/username/myapp:v1.0.0 - GitHub Container Registry

Command (Optional) - Override the container’s default entrypoint. Ports - Which ports your application listens on inside the container. For private registries, attach credentials to the service. See Private Registries.

Automatic Updates from External Registries

After a pre-built image is deployed, Suga polls the registry for a new digest at the same tag and rolls the service forward when one appears. Useful for:

Mutable tags like :latest, :stable, or :edge.
External CI pipelines that build outside Suga and push to a tag your service tracks.

Images Suga builds itself don’t wait on the poll — the build triggers the rollout directly when it finishes.

Pin to a specific version tag (e.g. myapp:v1.2.3) instead of :latest if you want the service to roll out only when you bump the tag.

Creating a Container

Open the Add palette

Click Add in the top right of the canvas, or right-click empty space. The palette is searchable and lists Service from GitHub, Service from Container, Template, Function, and Import Compose.

Pick a source

Choose Service from GitHub to build from source, Service from Container for a pre-built image from a registry, or Template for a pre-configured service. Then set the display name.

Set Port

If your app listens on a port, specify it. Enable HTTPS or TCP proxy for public access.

Add Environment Variables

Database URLs, API keys (mark as Sensitive), feature flags.

Set Resources

Allocate CPU and memory. New services start at 0.1 CPU and 128 MiB.

Apply

Click Apply to provision the container.

Supported Registries

Public (no credentials):

Docker Hub: nginx, postgres, redis
GitHub Container Registry: ghcr.io/username/image
Quay.io: quay.io/organization/image

Private (with credentials):

Docker Hub, GHCR, GCR, ECR, ACR, self-hosted

Enter credentials in the Service from Container dialog (or the service’s Config tab for an existing service), under Registry credentials. See Private Registries for setup.

Suga runs on Linux AMD64. If building on Apple Silicon, use --platform linux/amd64.

Docker Compose Import

Import existing Docker Compose files:

Open the Add palette and choose Import Compose
Paste YAML or upload file
Review parsed services
Import to canvas

Supported: Services, images, env vars, ports, named volumes, resource limits. Not supported: Build contexts (use pre-built images), bind mounts, health checks.

Functions

Functions run Deno code. Write TypeScript/JavaScript directly in the dashboard instead of building Docker images.

How Functions Work

Functions start an HTTP server on a configured port. Configuration (env vars, resources, networking, replicas) is identical to containers, but you write code in the Code tab instead of specifying an image. There’s no container build for functions. Your TypeScript ships with the deployment and runs on a managed Deno runtime, so changes go live in seconds. That makes functions a good fit for small APIs, webhooks, and quick prototyping.

Default Template

New functions use this Hono-based template:

import { Hono } from "npm:hono@^4";
import { serve } from "https://deno.land/std@0.224.0/http/server.ts";

const app = new Hono();

app.get("/", (c) => {
  return c.json({ message: "Hello from Deno function!" });
});

const port = parseInt(Deno.env.get("PORT") || "8080");
console.log(`Server running on port ${port}`);
serve(app.fetch, { port });

Your code must start an HTTP server on the configured port (default 8080).

Code Editor

Select function → Code tab → write code → Apply. The editor supports TypeScript syntax highlighting and basic completion.

Imports

// npm packages
import { Hono } from "npm:hono@^4";

// Deno standard library
import { serve } from "https://deno.land/std@0.224.0/http/server.ts";

// Third-party modules
import { Client } from "https://deno.land/x/postgres@v0.17.0/mod.ts";

Environment Variables

const dbUrl = Deno.env.get("DATABASE_URL");
const apiKey = Deno.env.get("API_KEY");

Configure in the Config tab. Mark sensitive values as Sensitive.

Common Configuration

Both containers and functions share these configuration options:

Resources

Each service is configured with CPU, memory, and replicas. Your allocation is a guaranteed floor, not a cap: services can burst above it for free, and billing is based on the allocation. See Billing and Resource Allocation for how that works and how to size a service, and Plan Limits for tier maximums, resource pools, volume limits, and the CPU/memory ratio rules.

Networking

Private - Services in the same environment communicate via service names:

http://api:3000
postgres:5432

Public HTTPS - Web traffic with automatic TLS through Cloudflare. Public TCP - Non-HTTP protocols (databases, SSH, custom protocols). See Networking for details.

Environment Variables

Key-value configuration for your services:

Database connection strings
API keys and secrets (mark as Sensitive)
Feature flags and settings

Volumes

Persistent storage that survives restarts and redeployments:

Mount paths inside the container
Size limits vary by plan
Single-mount only (one service per volume)

See Storage Reference for details.

Service Templates

Templates provide pre-configured services for common use cases:

PostgreSQL - Database with volume and default credentials
Redis - Cache with persistence options
MariaDB - MySQL-compatible database

Templates auto-generate secure passwords and configure networking.

Getting Started

Concepts

Configure

Operate

Agents

Reference

Tutorials

Comparisons

Support

What is a Service?

Containers vs. Functions

Containers

Build from GitHub

Build Configuration

Auto-Build on Push

Pre-built Image

Automatic Updates from External Registries

Creating a Container

Supported Registries

Docker Compose Import

Functions

How Functions Work

Default Template

Code Editor

Imports

Environment Variables

Common Configuration

Resources

Networking

Environment Variables

Volumes

Service Templates

​What is a Service?

​Containers vs. Functions

​Containers

​Build from GitHub

​Build Configuration

​Auto-Build on Push

​Pre-built Image

​Automatic Updates from External Registries

​Creating a Container

​Supported Registries

​Docker Compose Import

​Functions

​How Functions Work

​Default Template

​Code Editor

​Imports

​Environment Variables

​Common Configuration

​Resources

​Networking

​Environment Variables

​Volumes

​Service Templates

What is a Service?

Containers vs. Functions

Containers

Build from GitHub

Build Configuration

Auto-Build on Push

Pre-built Image

Automatic Updates from External Registries

Creating a Container

Supported Registries

Docker Compose Import

Functions

How Functions Work

Default Template

Code Editor

Imports

Environment Variables

Common Configuration

Resources

Networking

Environment Variables

Volumes

Service Templates