Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.suga.app/llms.txt

Use this file to discover all available pages before exploring further.

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

FeatureContainerFunction
RuntimeAny (Docker)Deno only
LanguageAnyTypeScript/JavaScript
ConfigurationImage + tagCode in editor
SetupDocker build externallyWrite code directly
AI AssistanceNoYes (Pro)
FlexibilityHighSimple and fast
Best ForFull applications, databasesAPIs, 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.
1

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.
2

Select Repository and Branch

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

Choose How to Build

Pick a Dockerfile from the repo, or let Suga build automatically by detecting your language and framework.
4

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.

​
Pre-built Image

[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.

​
Creating a Container

1

Add Container

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

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.
3

Set Port

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

Add Environment Variables

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

Set Resources

Allocate CPU and memory. Start with defaults (0.25 CPU, 512 MiB).
6

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:
  1. Select container → Config tab → Image section
  2. Check “Always pull image”
  3. Deploy

​
Docker Compose Import

Import existing Docker Compose files:
  1. Right-click canvas → “Import Compose”
  2. Paste YAML or upload file
  3. Review parsed services
  4. 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.

​
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:
Service configuration panel showing environment variables, networking, and resources

​
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:
PlanPer-request timeout
Free15 seconds
ProNo limit
EnterpriseNo 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.