Services - Suga Docs

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
AI Assistance	No	Yes (Pro)
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.

Deploy

Click “Deploy” 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

Add Container

Add a blank container or use a template on the canvas.

Configure Image

Set the display name, then choose your image source: a Pre-built Image from a registry, or Build from GitHub to build from source.

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. Start with defaults (0.25 CPU, 512 MiB).

Deploy

Click “Deploy” 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

Configure credentials in the Image Configuration section. See Private Registries for setup.

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

Always Pull Latest

For active development with the same tag, force fresh pulls:

Select container → Config tab → Image section
Check “Always pull image”
Deploy

Docker Compose Import

Import existing Docker Compose files:

Right-click canvas → “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 → Deploy. 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.

AI Assistant (Pro)

Pro plan includes the Vibe AI assistant in the code editor (500,000 tokens/month). It can help you write code, debug issues, and explain concepts.

Common Configuration

Both containers and functions share these configuration options:

Resources

Each service is configured with CPU, memory, and replicas. Limits depend on your plan. See Plan Limits for tier maximums, resource pools, volume limits, and the CPU/memory ratio rules.

Request Timeout by Plan

Each public HTTPS request is capped at a total time before the gateway returns a timeout response:

Plan	Per-request timeout
Free	15 seconds
Pro	No limit
Enterprise	No limit

The Free plan cap applies to the entire request lifetime — long-polling, large uploads or downloads, slow synchronous queries, and Server-Sent Events streams will be cut off at 15 seconds. WebSockets are not affected: the cap only bounds the initial upgrade handshake (which completes in milliseconds), after which the connection is governed by the 5-minute stream idle timeout — see Connection Timeouts.

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.

​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

​Always Pull Latest

​Docker Compose Import

​Functions

​How Functions Work

​Default Template

​Code Editor

​Imports

​Environment Variables

​AI Assistant (Pro)

​Common Configuration

​Resources

​Request Timeout by Plan

​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

Always Pull Latest

Docker Compose Import

Functions

How Functions Work

Default Template

Code Editor

Imports

Environment Variables

AI Assistant (Pro)

Common Configuration

Resources

Request Timeout by Plan

Networking

Environment Variables

Volumes

Service Templates