Go SDK: manage applications

Every method on this page lives on c.Apps and takes ctx first, then the app id. An appID can also be the composite <appId>-<workspaceId> of an app shared through a workspace. Each snippet below runs on its own inside this program: paste one at a time into main and run goimports (see Running the examples).

package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}

To list your apps, use c.Account.Me: its Applications slice has every app the key can see.

Getting an application

app, err := c.Apps.Get(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(app.ID, app.Name, app.Language, app.RAM, app.Cluster, app.CreatedAt)

Field	Type	Description
`ID` (`id`)	`string`	App id
`Name` (`name`)	`string`	Display name
`Description` (`desc`)	`string`	Description, `""` when unset
`Owner` (`owner`)	`string`	Owner’s user id
`Cluster` (`cluster`)	`string`	Cluster the app runs on
`RAM` (`ram`)	`int`	Allocated RAM in MB
`Language` (`language`)	`string`	Runtime language
`Domain` (`domain`)	`*string`	Default `<subdomain>.squareweb.app` host; `nil` for non-web apps
`Custom` (`custom`)	`*string`	Custom domain; `nil` when none is set
`CreatedAt` (`created_at`)	`time.Time`	Creation date

Status

Status(ctx, appID) returns the live state with formatted values:

status, err := c.Apps.Status(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(status.Status)  // e.g. "running", "exited"
fmt.Println(status.Running) // true
fmt.Println(status.CPU)     // "0.5%"
fmt.Println(status.RAM)     // "120.4MB" (RAM in use)
fmt.Println(status.Storage, status.Network.Total, status.Network.Now)
if status.Uptime != nil {
	fmt.Println(*status.Uptime) // Unix ms of the last start; nil when stopped
}

StatusRaw(ctx, appID) returns numbers instead (CPU in %, RAM in MB, Storage in bytes, Network.Total and Network.Now as [in, out] byte pairs):

raw, err := c.Apps.StatusRaw(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(raw.CPU, raw.RAM, raw.Network.Total) // 0.5 120.4 [1024 2048]

Uptime is a timestamp (when the app started), not a duration. Use time.Since(time.UnixMilli(*status.Uptime)) for how long it has been up.

Status of every application

StatusAll(ctx, workspaceID) returns one summary per app the key can see, in a single request. Pass "" for all apps, or a workspace id for the apps of that workspace only. CPU and RAM are only set (not "") while the app runs.

items, err := c.Apps.StatusAll(ctx, "")
if err != nil {
	log.Fatal(err)
}
for _, it := range items {
	if it.Running {
		fmt.Println(it.ID, it.CPU, it.RAM)
	} else {
		fmt.Println(it.ID, "stopped")
	}
}

Start, stop and restart

if err := c.Apps.Start(ctx, appID); err != nil {
	log.Fatal(err)
}
if err := c.Apps.Stop(ctx, appID); err != nil {
	log.Fatal(err)
}
if err := c.Apps.Restart(ctx, appID); err != nil {
	log.Fatal(err)
}

The server holds these calls open until the container acts, so without a ctx deadline they wait at least 2 minutes before timing out. When the platform refuses the action, the call returns an *APIError with status 409, a Code and an empty Message:

Code	Meaning
`CONTAINER_ALREADY_STARTED`	`start` on a running app
`CONTAINER_ALREADY_STOPPED`	`stop` on a stopped app
`CONTAINER_TEMPORARILY_SUSPENDED`	The app is suspended
`CONTAINER_NOT_FOUND`	The container does not exist on the cluster
`CONTAINER_INSUFFICIENT_DISK_SPACE`	Not enough disk to start
`CONTAINER_NETWORK_CONFLICT`	Network conflict on the cluster
`ACTION_FAILED`	The cluster could not perform the action

“Already started” and “already stopped” are errors too. If they mean success for you, handle them:

err := c.Apps.Start(ctx, appID)

var apiErr *squarecloud.APIError
if err != nil && !(errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeContainerAlreadyStarted) {
	log.Fatal(err)
}

Logs

Logs(ctx, appID) returns the latest console output as one string ("" when there is none).

logs, err := c.Apps.Logs(ctx, appID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(logs)

For a live stream of logs, use Realtime.

Metrics

Metrics(ctx, appID) returns the last 24 hours, one point every 5 minutes, newest first.

points, err := c.Apps.Metrics(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(points) > 0 {
	latest := points[0]
	fmt.Println(latest.Date, latest.CPU, latest.RAM, latest.Net)
}

Domains and load balancers

Domains(ctx) lists the default and custom hostnames of every app. LoadBalancers(ctx) lists the domains shared by several apps, with your plan’s limit.

domains, err := c.Apps.Domains(ctx)
if err != nil {
	log.Fatal(err)
}
for _, d := range domains {
	fmt.Println(d.AppID, d.Hostname, d.Type) // Type: "subdomain" | "custom"
}

lb, err := c.Apps.LoadBalancers(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(lb.Limit)
for _, balancer := range lb.Balancers {
	ids := make([]string, 0, len(balancer.Apps))
	for _, app := range balancer.Apps {
		ids = append(ids, app.ID)
	}
	fmt.Println(balancer.Hostname, ids)
}

To set a custom domain, see Network.

Deleting an application

if err := c.Apps.Delete(ctx, appID); err != nil {
	log.Fatal(err)
}

Deletion is permanent. Create a snapshot first if you may need the files again.

Next steps

Commit and upload

Create an app from a zip or send files to one.

Application API reference

The REST endpoints behind these methods.

Manage apps from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

Go SDK: manage applications

Getting an application

Status

Status of every application

Start, stop and restart

Logs

Metrics

Domains and load balancers

Deleting an application

Next steps

Commit and upload

Application API reference

Manage apps from the CLI

​Getting an application

​Status

​Status of every application

​Start, stop and restart

​Logs

​Metrics

​Domains and load balancers

​Deleting an application

​Next steps

Commit and upload

Application API reference

Manage apps from the CLI

Getting an application

Status

Status of every application

Start, stop and restart

Logs

Metrics

Domains and load balancers

Deleting an application

Next steps