Documentation
¶
Overview ¶
Package environment provides Docker environment setup and execution.
Index ¶
- Constants
- Variables
- func CheckDockerComposeAvailable(ctx context.Context) error
- func CheckDockerRunning(ctx context.Context) error
- func FallbackBoardURL(instanceName string) string
- func GenerateInstanceName(dirName string) string
- func GetDockerFile(name string) ([]byte, error)
- func Init(xfDir string, opts InitOptions) (written []string, err error)
- func IsOrbStack(ctx context.Context) (bool, error)
- func ListEmbeddedFiles() ([]string, error)
- func ProjectExists(ctx context.Context, instance string) (bool, error)
- func ReadEnvFile(path string) (map[string]string, error)
- func ReadInstanceName(xfDir string) (string, error)
- func RunComposer(ctx context.Context, xfDir string, stdin io.Reader, stdout, stderr io.Writer, ...) error
- func RunInDir(ctx context.Context, installationDir, workDir string, stdin io.Reader, ...) error
- func WriteEnvFile(path string, values map[string]string) error
- type InitOptions
- type Runner
- func (r *Runner) Compose(ctx context.Context, stdin io.Reader, stdout, stderr io.Writer, args ...string) error
- func (r *Runner) Contexts() []string
- func (r *Runner) DatabaseCredentials() (string, string)
- func (r *Runner) DatabaseName() string
- func (r *Runner) Destroy(ctx context.Context) error
- func (r *Runner) ExecInput(ctx context.Context, service string, env map[string]string, stdin io.Reader, ...) error
- func (r *Runner) ExecOrRun(ctx context.Context, service string, env map[string]string, stdin io.Reader, ...) error
- func (r *Runner) ExecOutput(ctx context.Context, service string, env map[string]string, stdout io.Writer, ...) error
- func (r *Runner) GetURL(ctx context.Context) (string, error)
- func (r *Runner) HasRunningServices(ctx context.Context) (bool, error)
- func (r *Runner) Instance() string
- func (r *Runner) IsServiceRunning(ctx context.Context, service string) (bool, error)
- func (r *Runner) PSInfo(ctx context.Context) ([]containerInfo, error)
- func (r *Runner) WaitForDatabase(ctx context.Context, checkInterval time.Duration) error
Constants ¶
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 ¶
var ( // ErrEnvNotInitialized indicates the Docker environment is not initialized. ErrEnvNotInitialized = errors.New("environment not initialized") )
Functions ¶
func CheckDockerComposeAvailable ¶
CheckDockerComposeAvailable returns an error if docker compose version fails.
func CheckDockerRunning ¶
CheckDockerRunning returns an error if docker info fails.
func FallbackBoardURL ¶
FallbackBoardURL returns the instance's conventional HTTPS development URL.
func GenerateInstanceName ¶
GenerateInstanceName generates a Docker-safe instance name from a directory name.
func GetDockerFile ¶
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. A pre-existing .env is not changed; instance and context defaults are applied only to a newly created .env.
func IsOrbStack ¶
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 ¶
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 ¶
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 ¶
ReadEnvFile reads environment variables from an .env file, skipping comments and malformed lines and removing matching surrounding quotes from values.
func ReadInstanceName ¶ added in v0.5.1
ReadInstanceName returns the XF_INSTANCE value from the .env file in xfDir. It returns "" if the file or value is missing.
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
RunInDir executes argv in the installation's container, or on the host only when the Docker environment is not initialized. workDir is relative to the installation; other runner errors do not trigger a host fallback.
Types ¶
type InitOptions ¶
InitOptions controls Docker configuration extraction. OverwriteExisting replaces existing base files, but not files generated from default templates. Contexts are written only when initialization creates a new .env file.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner handles Docker Compose operations for a XenForo installation.
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 ¶
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 ¶
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 ¶
DatabaseName returns the configured database name.
func (*Runner) Destroy ¶
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 ¶
GetURL returns the URL for accessing the XenForo site. It detects OrbStack vs standard Docker.
func (*Runner) HasRunningServices ¶
HasRunningServices reports whether the compose project has any running containers.
func (*Runner) IsServiceRunning ¶
IsServiceRunning reports whether the given compose service has a running container.