Documentation
¶
Overview ¶
Package project finds a project's Compose files and reads its x-mutti configuration.
Index ¶
Constants ¶
const ( UserHost = "host" UserService = "service" )
User values with a special meaning.
Variables ¶
var ErrNoComposeFile = errors.New("no Compose file found")
ErrNoComposeFile means no Compose file was found.
var ErrNoPlace = errors.New("no top-level key to put x-mutti before")
ErrNoPlace means a Compose file has no top-level block mapping to put x-mutti into.
Functions ¶
func Insert ¶
Insert puts block before the first top-level key of a Compose file, leaving every other byte as it was: comments, blank lines and formatting are the user's.
func ValidRoutePath ¶
ValidRoutePath reports whether p can be a route's path prefix.
Types ¶
type Config ¶
type Config struct {
// The project's name, part of every hostname. Default: the main worktree's directory name.
Name string `json:"name,omitempty"`
// The service behind the instance's main hostname. Default: the service publishing or
// exposing the most typical web port (80, 3000, 4200, 5173, 8000, 8080).
Main string `json:"main,omitempty"`
// HTTP routes per service. Default: the main service on the main hostname, every other
// service publishing or exposing an HTTP port on <service>.<main hostname>.
Routes map[string]Route `json:"routes,omitempty"`
// Container ports to publish on a fixed host port, per service, for tools that keep a
// connection setting, such as database GUIs. The port follows from instance, service and
// port, so it stays the same across restarts.
Ports map[string][]uint16 `json:"ports,omitempty"`
// Settings for mutti worktree add.
Worktree WorktreeConfig `json:"worktree,omitzero"`
// How mutti exec, mutti shell and hooks run commands.
Exec Exec `json:"exec,omitzero"`
// Commands run inside services at points of an instance's life.
Hooks Hooks `json:"hooks,omitzero"`
// Named sets of extra Compose files, enabled with --overlay <name>. Without --overlay, commands
// other than up and run use the overlays the instance was last started with.
Overlays map[string][]string `json:"overlays,omitempty"`
}
Config is the x-mutti block of a Compose file. Every field is optional.
func ParseConfig ¶
ParseConfig reads and validates the x-mutti block of a model. Unknown keys are errors, so a typo never silently does nothing.
func (Config) HTTPRoutes ¶
HTTPRoutes resolves the configured or default routes of a project under mainHost.
type Draft ¶
type Draft struct {
Main string `json:"main,omitempty"`
Routes map[string]uint16 `json:"routes,omitempty"` // service -> container port
Overlays map[string][]string `json:"overlays,omitempty"` // name -> files relative to the project dir
Ports map[string][]uint16 `json:"ports,omitempty"` // suggested fixed ports, written commented out
}
Draft is the x-mutti block mutti init writes: the main service and the overlays, plus the default routes and suggested fixed ports as comments to edit from.
type Exec ¶
type Exec struct {
// "host" (default): the host user's uid:gid, so files in bind mounts belong to you;
// "service": the image's user; or an explicit user[:group].
User string `json:"user,omitempty"`
// $HOME for commands run as the host user, who has no home in the image. Default /tmp.
Home string `json:"home,omitempty"`
}
Exec configures command execution inside services.
type Files ¶
Files are the Compose files of a project and the directory Compose treats as project dir.
type HTTPRoute ¶
type HTTPRoute struct {
Service string
Hosts []string // full hostnames
Paths []string // path prefixes on the main hostname
Port uint16
}
HTTPRoute is the resolved route of one service.
type Hook ¶
type Hook struct {
// Service to run the command in; it must be running.
Service string `json:"service"`
// Shell command, run with sh -c inside the service.
Run string `json:"run"`
// Like exec.user; empty means exec.user.
User string `json:"user,omitempty"`
}
Hook is one command.
type Hooks ¶
type Hooks struct {
// Once per instance, after its first successful up.
Bootstrap []Hook `json:"bootstrap,omitempty"`
// After every up.
PostUp []Hook `json:"post-up,omitempty"`
// Before down, destroy and reset; a failure is reported but does not stop the teardown.
PreDown []Hook `json:"pre-down,omitempty"`
// Instead of bootstrap when the data was copied from another instance
// (worktree add --data-from): the data needs no setup, the worktree may.
AfterClone []Hook `json:"after-clone,omitempty"`
// On mutti sweep, with MUTTI_SWEEP_OLDER_THAN in seconds: remove per-run resources the
// project made inside services, such as test databases named after run ids.
Sweep []Hook `json:"sweep,omitempty"`
}
Hooks are commands run inside services.
type Route ¶
type Route struct {
// Subdomain under the main hostname; "" is the main hostname itself. Default: the service
// name, or "" for the main service.
Host *string `json:"host,omitempty"`
// Path prefix on the main hostname that also leads to the service, e.g. /api.
Path string `json:"path,omitempty" jsonschema:"pattern=^/[A-Za-z0-9._~/-]*$"`
// Container port to send traffic to. Default: the service's first published TCP port, else
// its first exposed one.
Port uint16 `json:"port,omitempty"`
}
Route is how the router reaches one service.
type WorktreeConfig ¶
type WorktreeConfig struct {
// Files and directories (globs allowed) that git does not track but a worktree needs, such
// as .env.local; copied from the main worktree into new ones, never overwriting.
Copy []string `json:"copy,omitempty"`
}
WorktreeConfig configures new worktrees.