Documentation
¶
Index ¶
- Constants
- Variables
- func GenerateSchema() ([]byte, error)
- func ParseResourceReference(value any) (resourceName, outputName string, ok bool)
- type App
- func (a *App) GenerateMaintenanceMonitor(projectTitle string) *Monitor
- func (a *App) InstallCommands() []string
- func (a *App) IsTerraformManaged() bool
- func (a *App) Language() string
- func (a *App) MergeEnvironments(shared Environment) Environment
- func (a *App) OrderedCommands() []CommandSpec
- func (a *App) PrimaryDomain() string
- func (a *App) PrimaryDomainURL() string
- func (a *App) ShouldRelease() bool
- func (a *App) ShouldUseNPM() bool
- type AppType
- type Brand
- type Build
- type Command
- type CommandSpec
- type Contact
- type Definition
- func (d *Definition) ApplyDefaults() error
- func (d *Definition) ContainsGo() bool
- func (d *Definition) ContainsJS() bool
- func (d *Definition) FilterTerraformManaged() (*Definition, SkippedItems)
- func (d *Definition) GenerateMonitors() []Monitor
- func (d *Definition) GetAppsByType(appType AppType) []App
- func (d *Definition) GithubLabels() []string
- func (d *Definition) HasAppType(appType AppType) bool
- func (d *Definition) MergeAllEnvironments() Environment
- func (d *Definition) Validate(fs afero.Fs) []error
- type Domain
- type DomainType
- type EnvSource
- type EnvValue
- type EnvVar
- type EnvWalkEntry
- type Environment
- type EnvironmentWalker
- type EnvironmentWalkerE
- type GitHubRepo
- type Infra
- type MenuItem
- type Monitor
- type MonitorType
- type Monitoring
- type Project
- type Resource
- type ResourceBackupConfig
- type ResourceOutput
- type ResourceProvider
- type ResourceType
- type Shared
- type SkippedItems
- type Social
- type StatusPage
- type Tool
Constants ¶
const ( // MonitorIntervalHTTP is 1 minute for HTTP health checks. MonitorIntervalHTTP = 60 // MonitorIntervalDNS is 5 minutes for DNS resolution checks. MonitorIntervalDNS = 300 // MonitorIntervalBackup is 25 hours (90000s) for daily backup heartbeats with 1 hour buffer. MonitorIntervalBackup = 90000 // MonitorIntervalMaintenance is 8 days (691200s) for weekly maintenance with 1 day buffer. MonitorIntervalMaintenance = 691200 )
Monitor interval constants (in seconds).
const ( // JsonFileName defines the file name of the app manifest, // that should appear in the root of each webkit dir. JsonFileName = "app.json" )
Variables ¶
var Commands = []Command{ CommandFormat, CommandLint, CommandTest, CommandBuild, }
Commands defines all the Commands available that should be run in order.
Functions ¶
func GenerateSchema ¶ added in v0.2.0
GenerateSchema generates a JSON schema for the Definition type.
func ParseResourceReference ¶ added in v0.0.15
ParseResourceReference parses a resource reference string (e.g., "db.connection_url").
Resource references follow the format: "resource_name.output_name".
Types ¶
type App ¶
type App struct {
Name string `json:"name" validate:"required,lowercase,alphanumdash" description:"Unique identifier for the app (lowercase, hyphenated)"`
Title string `json:"title" validate:"required" description:"Human-readable app name for display purposes"`
Type AppType `json:"type" validate:"required,oneof=svelte-kit golang payload" description:"Application type (payload, svelte-kit, golang)"`
Description string `` /* 128-byte string literal not displayed */
Path string `json:"path" validate:"required" description:"Relative file path to the app's source code directory"`
Build Build `json:"build" description:"Build configuration for Docker containerisation"`
Infra Infra `json:"infra" validate:"required" description:"Infrastructure and deployment configuration"`
Env Environment `json:"env" description:"Environment variables specific to this app"`
Monitoring bool `json:"monitoring,omitempty" description:"Whether to enable uptime monitoring for this app (defaults to true)"`
UsesNPM *bool `json:"usesNPM" description:"Whether this app should be included in the pnpm workspace (auto-detected if not set)"`
TerraformManaged *bool `json:"terraformManaged,omitempty" description:"Whether this app's infrastructure is managed by Terraform (defaults to true)"`
Domains []Domain `json:"domains,omitzero" description:"Domain configurations for accessing this app"`
Tools map[string]Tool `json:"tools,omitempty" inline:"true" description:"Build tools required for CI/CD workflows"`
Commands *types.OrderedMap[Command, CommandSpec] `` /* 161-byte string literal not displayed */
}
App represents a single application within the webkit project. Each app has its own build configuration, infrastructure requirements, environment variables, and deployment settings. Apps can be of different types (Payload CMS, SvelteKit, GoLang) and are deployed independently.
func (*App) GenerateMaintenanceMonitor ¶ added in v0.7.0
GenerateMaintenanceMonitor creates a push monitor for an app's server maintenance workflow. It only generates a monitor if the app is deployed on a VM (infra type "vm") and monitoring is enabled. The monitor name follows the format: "{ProjectTitle} - {AppTitle} Maintenance". This creates a heartbeat monitor that can be pinged by CI/CD maintenance workflows.
func (*App) InstallCommands ¶ added in v0.4.0
InstallCommands returns the shell commands needed to install all tools for this app. Commands are generated based on the tool's Type field:
- "go": generates "go install <name>@<version>"
- "pnpm": generates "pnpm add -g <name>@<version>"
- "script": uses the Install field directly
If a tool provides an Install field, it overrides the auto-generated command.
func (*App) IsTerraformManaged ¶ added in v0.0.8
IsTerraformManaged returns whether this app should be managed by Terraform. It defaults to true when the field is nil or explicitly set to true.
func (*App) Language ¶
Language determines what language ecosystem a given app is. Either "go" or "js".
func (*App) MergeEnvironments ¶
func (a *App) MergeEnvironments(shared Environment) Environment
MergeEnvironments merges the shared env with the apps, with the app specific variables taking precedence.
func (*App) OrderedCommands ¶
func (a *App) OrderedCommands() []CommandSpec
OrderedCommands returns the app's commands in their defined order with Name populated. This includes both canonical commands (format, lint, test, build) and custom commands (e.g., generate) in the order they appear in the OrderedMap.
func (*App) PrimaryDomain ¶ added in v0.0.19
PrimaryDomain returns the primary domain for this app. It first looks for a domain with type "primary" in the Domains array. If no primary domain is found, it returns the first domain in the array. If the Domains array is empty, it returns an empty string.
func (*App) PrimaryDomainURL ¶ added in v0.5.0
PrimaryDomainURL returns the full HTTPS URL for the primary domain. If the app has no primary domain, it returns an empty string.
func (*App) ShouldRelease ¶ added in v0.0.10
ShouldRelease returns whether this app should be built and released in CI/CD. It defaults to true when the field is nil or explicitly set to true.
func (*App) ShouldUseNPM ¶
ShouldUseNPM returns whether this app should be included in pnpm workspace. It checks the UsesNPM field first, and if not set, defaults based on Language().
type AppType ¶
type AppType string
AppType defines the type of application being run.
type Brand ¶ added in v0.6.0
type Brand struct {
PrimaryColour string `json:"primaryColour,omitempty" validate:"omitempty,hexcolor" description:"Primary brand colour in hex format (e.g., #3B82F6)"`
SecondaryColour string `` /* 129-byte string literal not displayed */
LogoURL string `json:"logoUrl,omitempty" validate:"omitempty,url" description:"URL to the project's logo image"`
IconURL string `` /* 127-byte string literal not displayed */
}
Brand defines branding information for the project. This information is used for monitor tags, status pages, and other visual representations of the project.
type Build ¶
type Build struct {
Dockerfile string `json:"dockerfile" description:"Path to the Dockerfile relative to the app directory"`
Port int `json:"port,omitempty" validate:"omitempty,min=1,max=65535" description:"Port number the app listens on inside the container"`
Release *bool `json:"release,omitempty" description:"Whether to build and release this app in CI/CD (defaults to true)"`
}
Build defines Docker build configuration for containerised applications. These settings control how the app is built and exposed in container environments.
type Command ¶
type Command string
Command defines the type of action that will be actioned.
type CommandSpec ¶
type CommandSpec struct {
Name string `json:"-"`
Cmd string `json:"command,omitempty" description:"The shell command to execute (e.g., 'pnpm build')"`
SkipCI bool `json:"skip_ci,omitempty" description:"Whether to skip running this command in CI/CD pipelines"`
Timeout string `json:"timeout,omitempty" description:"Maximum execution time for the command (e.g., '5m', '1h')"`
Disabled bool `json:"-"` // Set during unmarshal
}
CommandSpec defines an action for an app that can run in CI/CD or locally. Commands can be specified as a boolean (enable/disable), a string (command override), or an object (full configuration with timeout and CI settings).
func (*CommandSpec) JSONSchemaOneOf ¶
func (*CommandSpec) JSONSchemaOneOf() []interface{}
JSONSchemaOneOf returns the polymorphic schema options.
func (*CommandSpec) UnmarshalJSON ¶
func (c *CommandSpec) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler to
type Definition ¶
type Definition struct {
Schema string `json:"$schema,omitempty" jsonschema:"-" description:"JSON Schema reference for IDE validation and autocomplete"`
WebkitVersion string `` /* 129-byte string literal not displayed */
Project Project `` /* 131-byte string literal not displayed */
Monitoring Monitoring `json:"monitoring,omitempty" description:"Monitoring configuration including status page and custom monitors"`
Resources []Resource `json:"resources" description:"Infrastructure resources such as databases and storage buckets"`
Apps []App `` /* 137-byte string literal not displayed */
}
Definition represents the complete webkit application configuration. It defines the structure of the app.json file used to configure all aspects of a webkit project including apps, resources, and infrastructure.
func Parse ¶ added in v0.5.0
func Parse(data []byte) (*Definition, error)
Parse unmarshals JSON bytes into a Definition and applies defaults.
func (*Definition) ApplyDefaults ¶
func (d *Definition) ApplyDefaults() error
ApplyDefaults ensures all required defaults are set on the Definition. This should be called after unmarshaling and before validation.
func (*Definition) ContainsGo ¶
func (d *Definition) ContainsGo() bool
ContainsGo returns true if any of the apps are marked as Go.
func (*Definition) ContainsJS ¶
func (d *Definition) ContainsJS() bool
ContainsJS returns true if any of the apps are marked as JS.
func (*Definition) FilterTerraformManaged ¶ added in v0.0.8
func (d *Definition) FilterTerraformManaged() (*Definition, SkippedItems)
FilterTerraformManaged creates a filtered copy of the Definition containing only apps and resources that are managed by Terraform.
Returns the filtered definition and information about what was skipped.
func (*Definition) GenerateMonitors ¶ added in v0.6.2
func (d *Definition) GenerateMonitors() []Monitor
GenerateMonitors creates all monitors for the definition. This includes: - HTTP and DNS monitors for app domains - Backup monitors for resources - Codebase backup monitor (always generated) - Maintenance monitors for VM apps - Custom monitors from project configuration
func (*Definition) GetAppsByType ¶ added in v0.0.8
func (d *Definition) GetAppsByType(appType AppType) []App
GetAppsByType returns all apps of the specified type from the definition.
func (*Definition) GithubLabels ¶
func (d *Definition) GithubLabels() []string
GithubLabels returns the labels that will appear on the GitHub repository by looking at the application types.
func (*Definition) HasAppType ¶ added in v0.0.8
func (d *Definition) HasAppType(appType AppType) bool
HasAppType checks if the definition contains an app of the specified type.
func (*Definition) MergeAllEnvironments ¶
func (d *Definition) MergeAllEnvironments() Environment
MergeAllEnvironments merges shared env variables with all apps' environments. App-specific values take precedence over shared ones. If multiple apps define the same variable, the last app in the list wins.
type Domain ¶
type Domain struct {
Name string `json:"name" validate:"required" description:"Domain name without protocol (e.g., 'example.com' or 'api.example.com')"`
Type DomainType `json:"type" validate:"omitempty,oneof=primary alias unmanaged" description:"Domain type (primary, alias, unmanaged)"`
Zone string `json:"zone,omitempty" description:"DNS zone for the domain if different from default"`
Wildcard bool `json:"wildcard,omitempty" description:"Whether this is a wildcard domain (e.g., '*.example.com')"`
}
Domain represents a domain name configuration for accessing an app. Domains can be primary, aliases, or unmanaged depending on your DNS setup.
type DomainType ¶
type DomainType string
DomainType defines the type of domain that should be provisioned.
const ( DomainTypePrimary DomainType = "primary" DomainTypeAlias DomainType = "alias" DomainTypeUnmanaged DomainType = "unmanaged" )
DomainType constants.
func (DomainType) Normalise ¶ added in v0.7.3
func (d DomainType) Normalise() DomainType
Normalise converts the domain type to lowercase for consistent internal comparisons.
func (DomainType) String ¶
func (d DomainType) String() string
String implements fmt.Stringer on the DomainType.
type EnvSource ¶
type EnvSource string
EnvSource defines the type of application being run.
const ( // EnvSourceValue is a static string value (default). // Example: "https://api.example.com" EnvSourceValue EnvSource = "value" // EnvSourceResource references a Terraform resource output. // Example: "db.connection_url" EnvSourceResource EnvSource = "resource" // EnvSourceSOPS is an encrypted secret stored in a SOPS file. // Example: "secrets/production.yaml:API_KEY" EnvSourceSOPS EnvSource = "sops" )
type EnvValue ¶
type EnvValue struct {
Source EnvSource `` /* 148-byte string literal not displayed */
// Value holds the actual value or reference depending on the source type:
// - "value": A static string (e.g., "https://api.example.com")
// - "resource": A Terraform resource reference (e.g., "db.connection_url")
// - "sops": The variable name/key to lookup in the SOPS file (e.g., "API_KEY")
Value any `json:"value,omitempty" description:"The value or reference for this variable (format depends on source type)"`
}
EnvValue represents a single environment variable configuration. It specifies both the source type and the value/reference for the variable.
type EnvVar ¶
EnvVar is a map of variable names to their value configurations. Each key is the environment variable name, and the value defines where the variable's value comes from (static value, resource output, or secret).
func CloneEnvVar ¶ added in v0.2.4
CloneEnvVar creates a shallow copy of an EnvVar map. This prevents mutation of the original map. Returns nil if the source is nil.
type EnvWalkEntry ¶
type EnvWalkEntry struct {
Environment env.Environment
Key string
Value any
Source EnvSource
Map EnvVar
}
EnvWalkEntry holds the details of a single env variable during iteration.
type Environment ¶
type Environment struct {
Default EnvVar `` /* 132-byte string literal not displayed */
Dev EnvVar `json:"dev,omitempty" inline:"true" description:"Environment variables specific to the development environment"`
Staging EnvVar `json:"staging,omitempty" inline:"true" description:"Environment variables specific to the staging environment"`
Production EnvVar `json:"production,omitempty" inline:"true" description:"Environment variables specific to the production environment"`
}
Environment contains environment-specific variable configurations. Variables can be defined per environment (dev, staging, production) or set once in 'default' to apply across all environments.
func (Environment) GetVarsForEnvironment ¶ added in v0.0.25
func (e Environment) GetVarsForEnvironment(target env.Environment) (EnvVar, error)
GetVarsForEnvironment returns the EnvVar map for the specified environment. Returns an error if the environment is unknown.
func (Environment) Walk ¶
func (e Environment) Walk(fn EnvironmentWalker)
Walk iterates over all environments and calls fn for each env variable.
func (Environment) WalkE ¶
func (e Environment) WalkE(fn EnvironmentWalkerE) error
WalkE iterates over all environments and calls fn for each env variable. If fn returns an error, iteration stops and the error is returned.
type EnvironmentWalker ¶
type EnvironmentWalker func(entry EnvWalkEntry)
EnvironmentWalker defines a function that processes one env entry.
type EnvironmentWalkerE ¶
type EnvironmentWalkerE func(entry EnvWalkEntry) error
EnvironmentWalkerE defines a function that processes one env entry and may return an error.
type GitHubRepo ¶
type GitHubRepo struct {
Owner string `json:"owner" validate:"required" description:"GitHub username or organisation that owns the repository"`
Name string `json:"name" validate:"required" description:"Repository name on GitHub"`
}
GitHubRepo defines the metadata for GitHub repositories. This information is used for CI/CD integration, secrets management, and linking documentation to the source repository.
type Infra ¶
type Infra struct {
Provider ResourceProvider `json:"provider" validate:"required" description:"Cloud infrastructure provider (digitalocean, backblaze)"`
Type string `json:"type" validate:"required" description:"Infrastructure type (vm, app, container, function)"`
Config map[string]any `json:"config" description:"Provider-specific infrastructure configuration options"`
}
Infra defines infrastructure and deployment configuration for an app. This includes the cloud provider, deployment type (VM, container, etc.), and provider-specific configuration options.
type Monitor ¶ added in v0.6.0
type Monitor struct {
Name string `json:"name" validate:"required" description:"Unique monitor name"`
Type MonitorType `json:"type" validate:"required,oneof=http dns postgres push" description:"Monitor type (http, dns, postgres, push)"`
URL string `json:"url,omitempty" description:"URL for HTTP monitors or database connection string for postgres monitors"`
Method string `json:"method,omitempty" description:"HTTP method for HTTP monitors (e.g., GET, POST)"`
Domain string `json:"domain,omitempty" description:"Domain name for DNS monitors"`
Interval int `json:"interval,omitempty" description:"Interval in seconds between checks (defaults based on monitor type if not specified)"`
MaxRedirects *int `` /* 144-byte string literal not displayed */
Identifier string `` /* 147-byte string literal not displayed */
}
Monitor contains minimal monitoring configuration.
Field usage by monitor type: - HTTP monitors: URL contains the full URL (including path), Method contains HTTP method - DNS monitors: Domain contains the domain name to check - Database monitors: URL contains database connection string or Terraform reference, Method is empty - Push monitors: URL and Method are empty
func (Monitor) VariableName ¶ added in v0.7.3
VariableName returns the GitHub Actions variable name for this monitor's ping URL. Format: {ENV}_{IDENTIFIER}_{TYPE}_PING_URL (e.g., PROD_DB_BACKUP_PING_URL). Only applicable for push monitors with an Identifier set.
type MonitorType ¶ added in v0.6.0
type MonitorType string
MonitorType defines the type of monitor.
const ( MonitorTypeHTTP MonitorType = "http" MonitorTypeDNS MonitorType = "dns" MonitorTypePostgres MonitorType = "postgres" MonitorTypePush MonitorType = "push" )
MonitorType constants.
func (MonitorType) String ¶ added in v0.6.0
func (m MonitorType) String() string
String implements fmt.Stringer on MonitorType.
type Monitoring ¶ added in v0.6.0
type Monitoring struct {
StatusPage StatusPage `json:"statusPage,omitempty" description:"Public status page configuration"`
Custom []Monitor `json:"custom,omitempty" description:"Custom monitors beyond auto-generated ones"`
}
Monitoring is the project-level monitoring configuration. It consolidates status page settings and custom monitors.
type Project ¶
type Project struct {
Name string `` /* 126-byte string literal not displayed */
Title string `json:"title" validate:"required" description:"Human-readable project name displayed in documentation and UIs"`
Description string `json:"description" validate:"required,max=200" description:"Brief description of the project's purpose and functionality"`
Repo GitHubRepo `json:"repo" validate:"required" description:"GitHub repository information for the project"`
Brand Brand `json:"brand,omitempty" description:"Branding configuration for the project including colours and logo"`
}
Project defines root metadata about the project such as business names and descriptions. This information is used throughout webkit for identification, documentation generation, and CI/CD configuration.
type Resource ¶
type Resource struct {
Name string `` /* 161-byte string literal not displayed */
Title string `json:"title" required:"true" validate:"required" description:"Human-readable resource name for display purposes"`
Type ResourceType `` /* 139-byte string literal not displayed */
Description string `` /* 133-byte string literal not displayed */
Provider ResourceProvider `` /* 187-byte string literal not displayed */
Config map[string]any `json:"config" description:"Provider-specific resource configuration (e.g., size, region, version)"`
Backup ResourceBackupConfig `json:"backup,omitempty" description:"Backup configuration for the resource"`
Monitoring bool `json:"monitoring,omitempty" description:"Whether to enable uptime monitoring for this resource (defaults to true)"`
TerraformManaged *bool `json:"terraformManaged,omitempty" description:"Whether this resource is managed by Terraform (defaults to true)"`
}
Resource represents an infrastructure component that applications depend on, such as databases, storage buckets, or caches. Resources are provisioned via Terraform and their outputs are made available to apps through environment variables.
func (*Resource) GenerateBackupMonitor ¶ added in v0.7.0
GenerateBackupMonitor creates a push monitor for a resource's backup workflow. It only generates a monitor if both backup and monitoring are enabled for the resource. The monitor name follows the format: "{ProjectTitle} - {ResourceTitle} Backup". This creates a heartbeat monitor that can be pinged by CI/CD backup workflows.
func (*Resource) GitHubSecretName ¶
func (r *Resource) GitHubSecretName(environment env.Environment, output string) string
GitHubSecretName returns the GitHub secret name for a resource output. Format: TF_{ENVIRONMENT}_{RESOURCE_NAME}_{OUTPUT_NAME} (uppercase)
Example:
resource.GitHubSecretName(env.Production, "connection_url") ↓ "TF_PROD_DB_CONNECTION_URL"
func (*Resource) IsTerraformManaged ¶ added in v0.0.8
IsTerraformManaged returns whether this resource should be managed by Terraform. It defaults to true when the field is nil or explicitly set to true.
type ResourceBackupConfig ¶
type ResourceBackupConfig struct {
Enabled bool `json:"enabled" description:"Whether to enable automated backups for this resource"`
}
ResourceBackupConfig defines backup behaviour for a resource. Backups are enabled by default for all resources that support them.
type ResourceOutput ¶ added in v0.5.0
ResourceOutput represents a single resource output with documentation.
type ResourceProvider ¶
type ResourceProvider string
ResourceProvider defines a provider of cloud infra.
const ( ResourceProviderDigitalOcean ResourceProvider = "digitalocean" ResourceProviderHetzner ResourceProvider = "hetzner" ResourceProviderBackBlaze ResourceProvider = "backblaze" ResourceProviderTurso ResourceProvider = "turso" )
ResourceProvider constants.
func (ResourceProvider) String ¶
func (r ResourceProvider) String() string
String implements fmt.Stringer on the ResourceProvider.
type ResourceType ¶
type ResourceType string
ResourceType defines the type of resource to be provisioned.
const ( ResourceTypePostgres ResourceType = "postgres" ResourceTypeS3 ResourceType = "s3" ResourceTypeSQLite ResourceType = "sqlite" )
ResourceType constants.
func (ResourceType) Documentation ¶ added in v0.5.0
func (r ResourceType) Documentation() []ResourceOutput
Documentation returns the available outputs for a resource type with descriptions, this is directly tied to Terraform outputs.
func (ResourceType) Outputs ¶
func (r ResourceType) Outputs() []string
Outputs returns the required outputs for a resource type for Terraform.
These should always be exported to GitHub secrets regardless of user config defined in the app definition.
func (ResourceType) String ¶
func (r ResourceType) String() string
String implements fmt.Stringer on the ResourceType.
type Shared ¶
type Shared struct {
}
Shared contains configuration that is shared across all applications in the project, such as common environment variables.
type SkippedItems ¶ added in v0.0.8
SkippedItems contains information about apps and resources that were filtered out due to not being Terraform managed.
type StatusPage ¶ added in v0.7.0
type StatusPage struct {
Domain string `` /* 183-byte string literal not displayed */
Slug string `` /* 194-byte string literal not displayed */
Theme string `` /* 144-byte string literal not displayed */
}
StatusPage defines the configuration for a project's status page. This information is used for custom domain setup and status page presentation.
type Tool ¶ added in v0.4.0
type Tool struct {
Type string `json:"type" inline:"true" description:"Installation method: 'go', 'pnpm', or 'script'"`
Name string `json:"name,omitempty" inline:"true" description:"Package path (for 'go') or package name (for 'pnpm')"`
Version string `json:"version,omitempty" inline:"true" description:"Version to install (e.g., 'latest', 'v0.2.543')"`
Install string `json:"install,omitempty" inline:"true" description:"Custom installation command (overrides auto-generated command)"`
}
Tool represents a build tool with its installation method. Supports three types: "go", "pnpm", and "script".
For "go" and "pnpm" types, the Name and Version fields are used to generate the installation command automatically.
For "script" type, the Install field must contain the complete installation command.
The Install field can be used with any type to override the auto-generated command.