hostmount

package
v1.0.40 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package hostmount answers one question for a panel that may be running in a container: where does the Docker daemon see this process's data directory?

A bind source is interpreted by the daemon in the host's filesystem, not in the panel's. When the panel runs in a container, a server directory it sees at /app/data/servers/x must be requested as /srv/carbon-panel/data/servers/x. Requiring the operator to restate that mapping in an environment variable is redundant: the panel can read it from its own container's mount table, which is also the only way to notice that the mount is missing or read-only.

Index

Constants

This section is empty.

Variables

View Source
var ErrNotMounted = errors.New("data directory is not a mounted volume")

ErrNotMounted reports that the container has no volume covering the data directory at all, so worlds would be written into the container layer.

Functions

func CheckMounted

func CheckMounted(dirs Dirs) error

CheckMounted refuses a data directory that is not on a persistent mount. It runs before the database is created, so a compose file with a missing or misspelt volume fails without writing anything into the container layer.

Only the data directory is fatal. Backups and scratch space may legitimately live somewhere this check cannot see (an S3-only deployment keeps a local scratch directory), so those are reported by UnmountedWarnings instead.

A panel running directly on a host has nothing to check and returns nil. So does a platform where mountinfo is not available; the daemon-backed check in Resolve still applies there.

func CheckOverride

func CheckOverride() error

CheckOverride validates the deprecated host-path override without needing a Docker client, so a relative value is rejected before the database is created. It is a no-op when the variable is unset.

func Configure

func Configure(m Mapping)

Configure publishes the resolved mapping. It is called once during startup. An empty mapping clears it, which is what a caller that wants the legacy fallback (a test, a maintenance command) does.

func Translate

func Translate(containerPath string) string

Translate maps a path onto the daemon's filesystem using the configured mapping. A process that never resolved one (a unit test, a maintenance command) falls back to the legacy environment override, so behaviour does not change under it.

func UnmountedWarnings

func UnmountedWarnings(dirs Dirs) []string

UnmountedWarnings names the non-critical directories that are not on a persistent mount. They are usable, but their contents do not survive a container recreate.

func ValidateDirs

func ValidateDirs(dirs Dirs) error

ValidateDirs checks that the directories the panel depends on are usable before anything writes to them. It is the check that turns a bad volume mapping into one clear error at startup instead of worlds silently landing in a container's writable layer.

Types

type Dirs

type Dirs struct {
	DataDir   string
	BackupDir string
	TempDir   string
}

Dirs are the directories the panel writes: server worlds, backups and scratch space. They are the ones that must survive a container recreate.

type Inspector

type Inspector interface {
	SelfMounts(ctx context.Context) ([]Mount, error)
}

Inspector reports the mounts of the container this process runs in. A nil slice with a nil error means the process is not running in a container the daemon knows about.

type Kind

type Kind string

Kind is the kind of a container mount.

const (
	// KindBind is a host path mounted into the container.
	KindBind Kind = "bind"
	// KindVolume is a Docker-managed volume.
	KindVolume Kind = "volume"
	// KindTmpfs is memory-backed and never holds server data.
	KindTmpfs Kind = "tmpfs"
)

type Mapping

type Mapping struct {
	// ContainerDir is the path this process writes to.
	ContainerDir string
	// HostDir is the path the daemon understands. It equals ContainerDir when
	// no translation is needed.
	HostDir string
	// Translated reports whether the two differ.
	Translated bool
	// Origin names where the mapping came from, for the startup log.
	Origin string
	// Mismatch reports that a deprecated override disagreed with the mapping
	// the daemon reported. The detected mapping still wins.
	Mismatch bool
	// OverrideDir is the override value that disagreed.
	OverrideDir string
}

Mapping is the resolved relationship between a directory as this process sees it and the same directory as the Docker daemon sees it.

func Current

func Current() Mapping

Current returns the resolved mapping, or the zero mapping when startup has not resolved one.

func Resolve

func Resolve(ctx context.Context, insp Inspector, dirs Dirs) (Mapping, error)

Resolve determines the host-side path of the data directory.

Detection is best effort and never fails a running deployment by itself:

  • when the process is not in a container, no translation is needed;
  • when the container's mount table names a mount that covers the data directory, that mount is authoritative, and a read-only, tmpfs or relative mount is a hard error because the panel would otherwise write worlds into a layer that is discarded with the container;
  • when the mount table cannot be read (a restricted Docker socket proxy, for example) the legacy override is used if it is present, and otherwise the panel runs without translation and says so.

func (Mapping) ToHost

func (m Mapping) ToHost(containerPath string) string

ToHost maps a path this process sees onto the daemon's filesystem. A path outside the container data directory is returned unchanged: it was never under the mapping.

type Mount

type Mount struct {
	Kind        Kind
	Source      string // the host path for a bind mount, the volume name for a volume
	Destination string // the path inside the container
	RW          bool
}

Mount is one entry of a container's mount table.

type NotMountedError

type NotMountedError struct {
	Dir     string
	Setting string
}

NotMountedError names the directory and the setting that produced it.

func (*NotMountedError) Error

func (e *NotMountedError) Error() string

Error names the directory and explains the consequence.

func (*NotMountedError) Is

func (e *NotMountedError) Is(target error) bool

Is lets callers test for ErrNotMounted whichever check produced the error.

Jump to

Keyboard shortcuts

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