environment

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package environment provides Docker environment setup and execution.

Index

Constants

View Source
const MaxInstanceNameLength = 48

MaxInstanceNameLength bounds every generated Docker instance name.

Instance names become Compose project names, container and volume name prefixes, image tags and hostnames. The tightest of those is a DNS label, at 63 characters; 48 leaves room for that while keeping URLs and container names short enough to read.

Variables

View Source
var (

	// ErrEnvNotInitialized indicates the Docker environment is not initialized.
	ErrEnvNotInitialized = errors.New("environment not initialized")
)

Functions

func CheckDockerComposeAvailable

func CheckDockerComposeAvailable(ctx context.Context) error

CheckDockerComposeAvailable checks if Docker Compose is available.

func CheckDockerRunning

func CheckDockerRunning(ctx context.Context) error

CheckDockerRunning checks if Docker is running.

func FallbackBoardURL

func FallbackBoardURL(instanceName string) string

FallbackBoardURL returns the board URL an instance is reachable at when it runs under OrbStack.

func GenerateInstanceName

func GenerateInstanceName(dirName string) string

GenerateInstanceName generates a Docker-safe instance name from a directory name.

func GetDockerFile

func GetDockerFile(name string) ([]byte, error)

GetDockerFile returns the contents of an embedded Docker file.

func Init

func Init(xfDir string, opts InitOptions) (written []string, err error)

Init initializes the Docker environment in a XenForo directory. It returns the paths of any ".default" files written alongside existing, user-modified files so callers can notify the user.

func IsOrbStack

func IsOrbStack(ctx context.Context) (bool, error)

IsOrbStack reports whether the Docker engine is OrbStack, which exposes container services to the host at <service>.<project>.orb.local without publishing ports.

func ListEmbeddedFiles

func ListEmbeddedFiles() ([]string, error)

ListEmbeddedFiles returns the repository-relative paths that extraction writes into a XenForo directory, in no particular order.

The list is derived from the embedded tree rather than hardcoded, so it cannot drift as files are added to or removed from it. ".default" files are reported under the name they are written as, matching extractDefaultFile.

func ProjectExists

func ProjectExists(ctx context.Context, instance string) (bool, error)

ProjectExists reports whether a Compose project already owns containers or volumes under the given instance name.

Compose derives container and volume names from the project name, so a second environment reusing one would adopt the first's resources. Volumes are checked as well as containers because `docker compose down` leaves volumes behind: an environment can be stopped with no containers at all and still collide.

A failed Docker command is returned as an error rather than reported as an absent project. Treating an unreachable Docker as "free" would let creation proceed onto a name that may already be in use.

func ReadEnvFile

func ReadEnvFile(path string) (map[string]string, error)

ReadEnvFile reads environment variables from an .env file.

func RunComposer

func RunComposer(ctx context.Context, xfDir string, stdin io.Reader, stdout, stderr io.Writer, args ...string) error

RunComposer runs Composer in the XenForo environment at xfDir, using exec for a running service or run for a stopped service. If no environment is configured, it runs Composer on the host in xfDir. Environment failures do not fall back to the host. Output writers must be non-nil.

func RunInDir

func RunInDir(ctx context.Context, installationDir, workDir string, stdin io.Reader, stdout, stderr io.Writer, argv ...string) error

func WriteEnvFile

func WriteEnvFile(path string, values map[string]string) error

WriteEnvFile writes values to an .env file. It preserves comments and formatting from an existing file if present.

Types

type InitOptions

type InitOptions struct {
	OverwriteExisting bool
	Contexts          []string
}

InitOptions contains options for initializing a Docker environment.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner handles Docker Compose operations for a XenForo installation.

func NewRunner

func NewRunner(xfDir string) (*Runner, error)

NewRunner creates a new Docker Compose runner for the given XenForo directory.

func (*Runner) Compose

func (r *Runner) Compose(ctx context.Context, stdin io.Reader, stdout, stderr io.Writer, args ...string) error

Compose runs a docker compose command directly with explicit stdio.

func (*Runner) Contexts

func (r *Runner) Contexts() []string

Contexts returns the compose contexts declared by XF_CONTEXTS, which select the environment's feature compose files (for example "mysql", "postgres" or "redis").

func (*Runner) DatabaseCredentials

func (r *Runner) DatabaseCredentials() (string, string)

DatabaseCredentials returns the configured database user and password.

The names must match what the compose files read, since those are the keys that end up in .env: XF_DB_USER and XF_DB_PASSWORD (compose.mysql.yaml, compose.postgres.yaml). The defaults mirror the fallbacks declared there.

Resolution order matches docker compose: process environment, then .env, then the built-in default.

func (*Runner) DatabaseName

func (r *Runner) DatabaseName() string

DatabaseName returns the configured database name.

func (*Runner) Destroy

func (r *Runner) Destroy(ctx context.Context) error

Destroy stops the environment and removes its volumes.

This is permanent: the database and any other volume data are deleted. It is what removing a worktree needs, since otherwise each discarded feature branch leaves a full volume set behind.

func (*Runner) ExecInput

func (r *Runner) ExecInput(ctx context.Context, service string, env map[string]string, stdin io.Reader, cmd ...string) error

ExecInput runs a command in a service, feeding it from stdin.

func (*Runner) ExecOrRun

func (r *Runner) ExecOrRun(ctx context.Context, service string, env map[string]string, stdin io.Reader, stdout, stderr io.Writer, cmd ...string) error

ExecOrRun uses exec for running services and falls back to run for stopped services.

env is passed as container environment variables so secrets stay out of the process list. The streams are explicit so interactive commands and progress writers behave the same whether the service is running or stopped. A TTY is requested only when stdin is a terminal.

func (*Runner) ExecOutput

func (r *Runner) ExecOutput(ctx context.Context, service string, env map[string]string, stdout io.Writer, cmd ...string) error

ExecOutput runs a command in a service, streaming its output to stdout.

Output is streamed rather than buffered so that large results, such as a database dump, do not have to fit in memory. Secrets belong in env rather than cmd: a value passed as a command argument is visible in the container's process list.

func (*Runner) GetURL

func (r *Runner) GetURL(ctx context.Context) (string, error)

GetURL returns the URL for accessing the XenForo site. It detects OrbStack vs standard Docker.

func (*Runner) HasRunningServices

func (r *Runner) HasRunningServices(ctx context.Context) (bool, error)

HasRunningServices reports whether the compose project has any running containers.

func (*Runner) Instance

func (r *Runner) Instance() string

Instance returns the Docker instance name.

func (*Runner) IsServiceRunning

func (r *Runner) IsServiceRunning(ctx context.Context, service string) (bool, error)

IsServiceRunning reports whether the given compose service has a running container.

func (*Runner) PSInfo

func (r *Runner) PSInfo(ctx context.Context) ([]containerInfo, error)

PSInfo returns container status parsed from `docker compose ps --format json`.

func (*Runner) WaitForDatabase

func (r *Runner) WaitForDatabase(ctx context.Context, checkInterval time.Duration) error

WaitForDatabase waits for the database to be ready.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL