config

package
v1.3.1 Latest Latest
Warning

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

Go to latest
Published: Apr 1, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddSite

func AddSite(site Site) error

AddSite appends or updates a site in the registry.

func BinDir

func BinDir() string

BinDir returns the lerd bin directory.

func CertsDir

func CertsDir() string

CertsDir returns the certs directory.

func ConfigDir

func ConfigDir() string

ConfigDir returns ~/.config/lerd/ (or $XDG_CONFIG_HOME/lerd/).

func ContainerHostsFile added in v1.2.4

func ContainerHostsFile() string

ContainerHostsFile returns the path to the shared hosts file mounted into PHP containers.

func CountSitesUsingService added in v1.0.0

func CountSitesUsingService(name string) int

CountSitesUsingService returns how many active (non-ignored, non-paused) site .env files reference lerd-{name}, i.e. are configured to use the service.

func CustomServicesDependingOn added in v1.0.0

func CustomServicesDependingOn(name string) []string

CustomServicesDependingOn returns the names of all custom services that declare name in their depends_on list.

func CustomServicesDir added in v0.5.4

func CustomServicesDir() string

CustomServicesDir returns the directory for custom service YAML files.

func DataDir

func DataDir() string

DataDir returns ~/.local/share/lerd/ (or $XDG_DATA_HOME/lerd/).

func DataSubDir

func DataSubDir(name string) string

DataSubDir returns a named subdirectory under data.

func DetectFramework added in v1.0.0

func DetectFramework(dir string) (string, bool)

DetectFramework inspects dir and returns the detected framework name. It checks laravel first (built-in), then user-defined frameworks in FrameworksDir(). Returns ("", false) if no framework matches.

func DetectPublicDir added in v1.0.0

func DetectPublicDir(dir string) string

DetectPublicDir inspects dir for a well-known PHP public directory and returns it. It checks directories used by common PHP frameworks in priority order. A candidate is accepted only if it contains an index.php file, ensuring the directory is actually the document root and not an empty placeholder. Returns "." if no valid candidate is found (serve from project root).

func DnsmasqDir

func DnsmasqDir() string

DnsmasqDir returns the dnsmasq config directory.

func FrameworksDir added in v1.0.0

func FrameworksDir() string

FrameworksDir returns the directory for user-defined framework YAML files.

func GetConsoleCommand added in v1.2.0

func GetConsoleCommand(projectDir string) (string, error)

GetConsoleCommand returns the console binary (without the "php" prefix) for the framework detected in projectDir. It checks the site registry first, then falls back to auto-detection. For Laravel the default is "artisan".

func GlobalConfigFile

func GlobalConfigFile() string

GlobalConfigFile returns the path to config.yaml.

func IgnoreSite added in v0.3.0

func IgnoreSite(name string) error

IgnoreSite marks a site as ignored (used for parked sites that have been unlinked).

func NginxConfD

func NginxConfD() string

NginxConfD returns the nginx conf.d directory.

func NginxDir

func NginxDir() string

NginxDir returns the nginx data directory.

func PHPConfFile added in v0.4.0

func PHPConfFile(version string) string

PHPConfFile returns the host path for the per-version xdebug ini file.

func PHPImageHashFile added in v0.1.25

func PHPImageHashFile() string

PHPImageHashFile returns the path to the stored PHP-FPM Containerfile hash.

func PHPUserIniFile added in v0.5.5

func PHPUserIniFile(version string) string

PHPUserIniFile returns the host path for the per-version user php.ini file.

func PausedDir added in v1.0.0

func PausedDir() string

PausedDir returns the directory where paused-site landing page HTML files are stored.

func QuadletDir

func QuadletDir() string

QuadletDir returns the Podman quadlet directory.

func RemoveCustomService added in v0.5.4

func RemoveCustomService(name string) error

RemoveCustomService deletes a custom service config file.

func RemoveFramework added in v1.0.0

func RemoveFramework(name string) error

RemoveFramework deletes a user-defined framework YAML. For "laravel" it only removes the user workers overlay (the built-in definition remains).

func RemoveSite

func RemoveSite(name string) error

RemoveSite removes a site by name from the registry.

func SaveCustomService added in v0.5.4

func SaveCustomService(svc *CustomService) error

SaveCustomService validates and writes a custom service config to disk.

func SaveFramework added in v1.0.0

func SaveFramework(fw *Framework) error

SaveFramework writes a framework definition to FrameworksDir()/{name}.yaml. For the laravel built-in, only the Workers field is persisted (other fields come from the built-in definition and are always merged in by GetFramework).

func SaveGlobal

func SaveGlobal(cfg *GlobalConfig) error

SaveGlobal writes the configuration to config.yaml.

func SaveProjectConfig added in v1.2.0

func SaveProjectConfig(dir string, cfg *ProjectConfig) error

SaveProjectConfig writes cfg to .lerd.yaml in dir.

func SaveSites

func SaveSites(reg *SiteRegistry) error

SaveSites writes the registry to sites.yaml.

func ServiceIsManuallyStarted added in v1.0.0

func ServiceIsManuallyStarted(name string) bool

ServiceIsManuallyStarted returns true if the service was explicitly started by the user (via `lerd service start` or the dashboard), making it exempt from auto-stop when no sites reference it.

func ServiceIsPaused added in v0.6.0

func ServiceIsPaused(name string) bool

ServiceIsPaused returns true if the service was manually stopped by the user.

func ServiceIsPinned added in v1.0.0

func ServiceIsPinned(name string) bool

ServiceIsPinned returns true if the service has been pinned by the user, meaning it will never be auto-stopped even when no sites reference it.

func SetServiceManuallyStarted added in v1.0.0

func SetServiceManuallyStarted(name string, v bool) error

SetServiceManuallyStarted marks or clears the manually-started flag for the named service.

func SetServicePaused added in v0.6.0

func SetServicePaused(name string, paused bool) error

SetServicePaused marks or clears the manual-stop flag for the named service.

func SetServicePinned added in v1.0.0

func SetServicePinned(name string, v bool) error

SetServicePinned marks or clears the pinned flag for the named service.

func SitesFile

func SitesFile() string

SitesFile returns the path to sites.yaml.

func SystemdUserDir

func SystemdUserDir() string

SystemdUserDir returns the systemd user unit directory.

func UpdateCheckFile added in v0.9.0

func UpdateCheckFile() string

UpdateCheckFile returns the path to the cached update-check state file.

Types

type CustomService added in v0.5.4

type CustomService struct {
	Name        string            `yaml:"name"`
	Image       string            `yaml:"image"`
	Ports       []string          `yaml:"ports,omitempty"`
	Environment map[string]string `yaml:"environment,omitempty"`
	DataDir     string            `yaml:"data_dir,omitempty"`
	Exec        string            `yaml:"exec,omitempty"`
	EnvVars     []string          `yaml:"env_vars,omitempty"`
	EnvDetect   *EnvDetect        `yaml:"env_detect,omitempty"`
	SiteInit    *SiteInit         `yaml:"site_init,omitempty"`
	Dashboard   string            `yaml:"dashboard,omitempty"`
	Description string            `yaml:"description,omitempty"`
	DependsOn   []string          `yaml:"depends_on,omitempty"`
}

CustomService represents a user-defined OCI-based service.

func ListCustomServices added in v0.5.4

func ListCustomServices() ([]*CustomService, error)

ListCustomServices returns all custom services defined in the services directory.

func LoadCustomService added in v0.5.4

func LoadCustomService(name string) (*CustomService, error)

LoadCustomService loads a custom service by name from the services directory.

func LoadCustomServiceFromFile added in v0.5.4

func LoadCustomServiceFromFile(path string) (*CustomService, error)

LoadCustomServiceFromFile parses a CustomService from any YAML file path.

type EnvDetect added in v0.5.4

type EnvDetect struct {
	Key         string `yaml:"key"`
	ValuePrefix string `yaml:"value_prefix,omitempty"`
}

EnvDetect defines auto-detection rules for `lerd env`.

type Framework added in v1.0.0

type Framework struct {
	Name      string                     `yaml:"name"`
	Label     string                     `yaml:"label"`
	Detect    []FrameworkRule            `yaml:"detect,omitempty"`
	PublicDir string                     `yaml:"public_dir"`
	Env       FrameworkEnvConf           `yaml:"env,omitempty"`
	Composer  string                     `yaml:"composer,omitempty"` // auto | true | false
	NPM       string                     `yaml:"npm,omitempty"`      // auto | true | false
	Workers   map[string]FrameworkWorker `yaml:"workers,omitempty"`
	// Console is the console command to run (without 'php' prefix).
	// Example: "artisan", "bin/console"
	Console string `yaml:"console,omitempty"`
	// Create is the scaffold command used by "lerd new". The target directory is appended automatically.
	// Example: "composer create-project --no-install --no-plugins --no-scripts laravel/laravel"
	Create string `yaml:"create,omitempty"`
}

Framework describes a PHP project framework type.

func GetFramework added in v1.0.0

func GetFramework(name string) (*Framework, bool)

GetFramework returns the framework definition for the given name. For non-laravel frameworks it checks user-defined YAMLs in FrameworksDir(). For laravel it always starts from the built-in and merges any user-defined workers on top, so queue/schedule/reverb are always available. Returns (nil, false) if the framework is not found.

func ListFrameworks added in v1.0.0

func ListFrameworks() []*Framework

ListFrameworks returns all available framework definitions: the laravel built-in plus any user-defined YAMLs in FrameworksDir().

type FrameworkEnvConf added in v1.0.0

type FrameworkEnvConf struct {
	File           string `yaml:"file,omitempty"`            // primary env file (relative to project)
	ExampleFile    string `yaml:"example_file,omitempty"`    // example to copy from if File missing
	Format         string `yaml:"format,omitempty"`          // dotenv | php-const (default: dotenv)
	FallbackFile   string `yaml:"fallback_file,omitempty"`   // used when File doesn't exist
	FallbackFormat string `yaml:"fallback_format,omitempty"` // format for FallbackFile

	// URLKey is the env key that holds the application URL (default: APP_URL).
	URLKey string `yaml:"url_key,omitempty"`

	// Services defines per-service detection rules and env vars to apply.
	// Keys match the built-in service names: mysql, postgres, redis, meilisearch, rustfs, mailpit.
	Services map[string]FrameworkServiceDef `yaml:"services,omitempty"`
}

FrameworkEnvConf describes how the framework manages its env file.

func (FrameworkEnvConf) Resolve added in v1.0.0

func (e FrameworkEnvConf) Resolve(projectDir string) (file, format string)

Resolve returns the env file path and format to use for the given project directory. It returns the primary file if it exists, otherwise the fallback. Defaults to ".env" with "dotenv" format if nothing is configured.

type FrameworkRule added in v1.0.0

type FrameworkRule struct {
	File     string `yaml:"file,omitempty"`     // file must exist in project root
	Composer string `yaml:"composer,omitempty"` // package must be in composer.json require/require-dev
}

FrameworkRule is a single detection rule for a framework. Any matching rule is sufficient to identify the framework.

type FrameworkServiceDef added in v1.0.0

type FrameworkServiceDef struct {
	// Detect lists env key conditions; any match signals the service is in use.
	Detect []FrameworkServiceDetect `yaml:"detect,omitempty"`
	// Vars is the list of KEY=VALUE pairs to apply when the service is detected.
	// Use {{site}} for the per-project database name.
	Vars []string `yaml:"vars,omitempty"`
}

FrameworkServiceDef describes how a service is detected and configured for a framework.

type FrameworkServiceDetect added in v1.0.0

type FrameworkServiceDetect struct {
	Key         string `yaml:"key"`
	ValuePrefix string `yaml:"value_prefix,omitempty"`
}

FrameworkServiceDetect is a single detection condition. The service is considered active when Key exists in the env file and, if ValuePrefix is set, its value starts with that prefix.

type FrameworkWorker added in v1.0.0

type FrameworkWorker struct {
	Label   string `yaml:"label,omitempty"`
	Command string `yaml:"command"`
	Restart string `yaml:"restart,omitempty"` // always | on-failure (default: always)
}

FrameworkWorker describes a long-running process managed as a systemd service. The Command is executed inside the PHP-FPM container for the site.

type GlobalConfig

type GlobalConfig struct {
	PHP struct {
		DefaultVersion string              `yaml:"default_version" mapstructure:"default_version"`
		XdebugEnabled  map[string]bool     `yaml:"xdebug_enabled"  mapstructure:"xdebug_enabled"`
		Extensions     map[string][]string `yaml:"extensions"      mapstructure:"extensions"`
	} `yaml:"php" mapstructure:"php"`
	Node struct {
		DefaultVersion string `yaml:"default_version" mapstructure:"default_version"`
	} `yaml:"node" mapstructure:"node"`
	Nginx struct {
		HTTPPort  int `yaml:"http_port"  mapstructure:"http_port"`
		HTTPSPort int `yaml:"https_port" mapstructure:"https_port"`
	} `yaml:"nginx" mapstructure:"nginx"`
	DNS struct {
		TLD string `yaml:"tld" mapstructure:"tld"`
	} `yaml:"dns" mapstructure:"dns"`
	ParkedDirectories []string                 `yaml:"parked_directories" mapstructure:"parked_directories"`
	Services          map[string]ServiceConfig `yaml:"services"           mapstructure:"services"`
}

GlobalConfig is the top-level lerd configuration.

func LoadGlobal

func LoadGlobal() (*GlobalConfig, error)

LoadGlobal reads config.yaml via viper, returning defaults if the file is absent.

func (*GlobalConfig) AddExtension added in v0.5.5

func (c *GlobalConfig) AddExtension(version, ext string)

AddExtension adds ext to the custom extension list for version (no-op if already present).

func (*GlobalConfig) GetExtensions added in v0.5.5

func (c *GlobalConfig) GetExtensions(version string) []string

GetExtensions returns the custom extensions configured for the given PHP version.

func (*GlobalConfig) IsXdebugEnabled added in v0.4.0

func (c *GlobalConfig) IsXdebugEnabled(version string) bool

IsXdebugEnabled returns true if Xdebug is enabled for the given PHP version.

func (*GlobalConfig) RemoveExtension added in v0.5.5

func (c *GlobalConfig) RemoveExtension(version, ext string)

RemoveExtension removes ext from the custom extension list for version.

func (*GlobalConfig) SetXdebug added in v0.4.0

func (c *GlobalConfig) SetXdebug(version string, enabled bool)

SetXdebug enables or disables Xdebug for the given PHP version.

type ProjectConfig added in v1.2.0

type ProjectConfig struct {
	PHPVersion   string           `yaml:"php_version,omitempty"`
	NodeVersion  string           `yaml:"node_version,omitempty"`
	Framework    string           `yaml:"framework,omitempty"`
	FrameworkDef *Framework       `yaml:"framework_def,omitempty"`
	Secured      bool             `yaml:"secured,omitempty"`
	Services     []ProjectService `yaml:"services,omitempty"`
}

ProjectConfig holds per-project configuration stored in .lerd.yaml.

func LoadProjectConfig added in v1.2.0

func LoadProjectConfig(dir string) (*ProjectConfig, error)

LoadProjectConfig reads .lerd.yaml from dir, returning an empty config if the file does not exist.

func (*ProjectConfig) ServiceNames added in v1.3.0

func (p *ProjectConfig) ServiceNames() []string

ServiceNames returns the name of every service in the config, for callers that only need the list of names (e.g. the init wizard multi-select).

type ProjectService added in v1.3.0

type ProjectService struct {
	Name   string
	Custom *CustomService // nil for named references
}

ProjectService is either a named reference to a built-in or custom service (e.g. "redis") or an inline custom service definition.

YAML forms:

  • redis # named reference
  • mongodb: # inline definition image: mongo:7 ...

func (ProjectService) MarshalYAML added in v1.3.0

func (s ProjectService) MarshalYAML() (interface{}, error)

MarshalYAML serialises back to the compact form: plain string for named references, single-key map for inline definitions.

func (*ProjectService) UnmarshalYAML added in v1.3.0

func (s *ProjectService) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML handles both scalar ("redis") and mapping ({mongodb: {...}}) forms of a service entry.

type ServiceConfig

type ServiceConfig struct {
	Enabled    bool     `yaml:"enabled"      mapstructure:"enabled"`
	Image      string   `yaml:"image"        mapstructure:"image"`
	Port       int      `yaml:"port"         mapstructure:"port"`
	ExtraPorts []string `yaml:"extra_ports"  mapstructure:"extra_ports"`
}

ServiceConfig holds configuration for an optional service.

type Site

type Site struct {
	Name          string   `yaml:"name"`
	Domain        string   `yaml:"domain"`
	Path          string   `yaml:"path"`
	PHPVersion    string   `yaml:"php_version"`
	NodeVersion   string   `yaml:"node_version"`
	Secured       bool     `yaml:"secured"`
	Ignored       bool     `yaml:"ignored,omitempty"`
	Paused        bool     `yaml:"paused,omitempty"`
	PausedWorkers []string `yaml:"paused_workers,omitempty"`
	Framework     string   `yaml:"framework,omitempty"`
	PublicDir     string   `yaml:"public_dir,omitempty"`
}

Site represents a single registered Lerd site.

func FindSite

func FindSite(name string) (*Site, error)

FindSite returns the site with the given name, or an error if not found.

func FindSiteByDomain added in v0.1.37

func FindSiteByDomain(domain string) (*Site, error)

FindSiteByDomain returns the site with the given domain, or an error if not found.

func FindSiteByPath added in v0.3.0

func FindSiteByPath(path string) (*Site, error)

FindSiteByPath returns the site whose path matches, or an error if not found.

func (*Site) IsLaravel added in v1.0.0

func (s *Site) IsLaravel() bool

IsLaravel returns true if this site uses the Laravel framework.

type SiteInit added in v0.5.4

type SiteInit struct {
	// Container to exec into. Defaults to lerd-<service name>.
	Container string `yaml:"container,omitempty"`
	// Exec is passed to sh -c inside the container.
	Exec string `yaml:"exec"`
}

SiteInit defines an optional command to run inside the service container once per project when `lerd env` detects this service. Use it for any per-site setup: creating a database, a user, indexes, etc. The exec string may contain {{site}} and {{site_testing}} placeholders, which are replaced with the project site handle at runtime.

type SiteRegistry

type SiteRegistry struct {
	Sites []Site `yaml:"sites"`
}

SiteRegistry holds all registered sites.

func LoadSites

func LoadSites() (*SiteRegistry, error)

LoadSites reads sites.yaml, returning an empty registry if the file does not exist.

Jump to

Keyboard shortcuts

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