deploy

Documentation

Overview

Package deploy is the resource module for deploying applications and containers onto VMs the tenant node can SSH into.

Two surfaces:

• Container: drop a single Docker container onto a VM (POST /api/v2/tenant/container/deploy). Equivalent to `vxcli deploy container`.
• Stack: clone a git repo (or upload a bundle), build it, and run it fronted by nginx (POST /api/v2/infrastructure/services/<stack>/deploy). Equivalent to `vxcli deploy <react|fastapi|golang|...>`.

Cloud-side provisioning (EC2, S3, IAM) lives in package nodes/cloud (not in this preview).

Index

• type Client
  • func (c *Client) Container(ctx context.Context, opts ContainerOpts) (*Result, error)
  • func (c *Client) Stack(ctx context.Context, kind Stack, opts StackOpts) (*Result, error)
• type ContainerOpts
• type Result
• type SSH
• type Stack
• type StackOpts

Types

type Client

type Client struct {
	T              *transport.Transport
	NodeURL        string
	AuthedUsername string
}

Client is the deploy resource module.

func (*Client) Container

func (c *Client) Container(ctx context.Context, opts ContainerOpts) (*Result, error)

Container drops a single Docker container onto a VM.

Endpoint: POST /api/v2/tenant/container/deploy.

func (*Client) Stack

func (c *Client) Stack(ctx context.Context, kind Stack, opts StackOpts) (*Result, error)

Stack runs a language-stack deploy against a remote VM. The available stacks are enumerated by the Stack constants above. Note: as of preview, nodejs/python/nextjs/static stack scripts have a server-side template substitution bug — vxsdk faithfully forwards the call, but those four will fail with exit status 1 until the platform fixes it.

type ContainerOpts

type ContainerOpts struct {
	SSH SSH

	Name          string   // container name override (defaults to image basename)
	Image         string   // registry/image:tag (required)
	Ports         []string // "host:container" pairs, e.g. {"3000:3000"}
	Volumes       []string // "host_path:container_path" pairs
	Env           []string // KEY=VALUE pairs
	RestartPolicy string   // "unless-stopped" (default), "always", "no"
	Network       string   // optional docker network
	Command       string   // optional override of CMD
	CapAdd        []string
	Devices       []string
	Sysctls       []string

	// Private registry auth — set EITHER DockerRegistrySlug (workspace
	// vault entry name) OR DockerUsername/DockerPassword.
	DockerRegistrySlug string
	DockerUsername     string
	DockerPassword     string

	// HTTPS — when EnableSSL is set with a Domain, the deploy installs nginx +
	// a Let's Encrypt cert in front of the first published port once the
	// container is healthy. The Domain's A record must already point to the VM.
	EnableSSL bool
	Domain    string
	SSLEmail  string
}

ContainerOpts describes a single-container deploy onto a VM.

type Result

type Result struct {
	SessionID    string `json:"session_id"`
	Status       string `json:"status,omitempty"`
	Hostname     string `json:"hostname,omitempty"`
	ResourceName string `json:"resource_name,omitempty"`
	AccessURL    string `json:"access_url,omitempty"`
	ExitCode     int    `json:"exit_code,omitempty"`
}

Result mirrors install.Result. New fields may be added.

type SSH

type SSH = install.SSH

SSH is re-exported from install/ since the SSH triple is shared.

type Stack

type Stack string

Stack identifies which language deployer the node should run.

const (
	StackReact   Stack = "react"
	StackNextJS  Stack = "nextjs"
	StackNodeJS  Stack = "nodejs"
	StackFastAPI Stack = "fastapi"
	StackPython  Stack = "python"
	StackDjango  Stack = "django"
	StackGolang  Stack = "golang"
	StackRust    Stack = "rust"
	StackCpp     Stack = "cpp"
	StackPHP     Stack = "php"
	StackStatic  Stack = "static"
)

type StackOpts

type StackOpts struct {
	SSH SSH

	AppName string // app identifier (defaults to repo basename)
	RepoURL string // git URL (required for repo-based deploys)
	Branch  string // default "main"

	// Git auth for private repos. GitToken accepts the literal "vault:"
	// to resolve from workspace vault — same convention as vxcli.
	GitProvider string // "github" | "gitlab" | "bitbucket"
	GitUsername string
	GitToken    string

	// Stack-specific knobs. Empty values fall back to platform defaults.
	BuildMode    string // "production" | "development" (react/nextjs)
	Entry        string // entry script / module:app
	Requirements string // path to requirements.txt (python/fastapi)
	Framework    string // express, fastify, etc. (nodejs)
	GoVersion    string // golang
	NodeVersion  string // ignored — server rejected as of preview
	HTTPPort     string // nginx-side port (default "80")
	HTTPSPort    string // default "443"
	AppPort      string // app-side port

	EnvVars string // newline-separated KEY=value

	// HTTPS / Traefik — when EnableSSL is set with a Domain, the service is
	// fronted at https://<Domain> by the shared Traefik proxy. ExposeDirectPort
	// also keeps the raw ip:port published (https + ip:port both reachable).
	EnableSSL        bool
	Domain           string
	SSLEmail         string
	ExposeDirectPort bool
}

StackOpts describes a language-stack git-clone-and-build deploy.