template

README

Nexlayer Template Package

This package is the single source of truth for all Nexlayer template-related code.

Template Structure

version: v2
application:
  name: myapp
  url: https://myapp.nexlayer.dev
  registryLogin:
    registry: docker.io
    username: myuser
    personalAccessToken: token123
  pods:
    - name: web
      type: frontend
      image: myapp/web:latest
      vars:
        - key: REACT_APP_API_URL
          value: http://api:8080
      servicePorts:
        - 3000

Supported Pod Types

Frontend

• frontend: Generic frontend
• react: React.js application
• angular: Angular application
• vue: Vue.js application

Backend

• backend: Generic backend
• express: Express.js application
• django: Django application
• fastapi: FastAPI application

Database

• database: Generic database
• mongodb: MongoDB database
• postgres: PostgreSQL database
• redis: Redis database
• neo4j: Neo4j database

Other

• nginx: NGINX web server/proxy
• llm: Large Language Model service

Default Images

Each pod type has a default Docker image. See defaults.go for the complete mapping.

Examples:

• postgres → docker.io/library/postgres:latest
• redis → docker.io/library/redis:7
• mongodb → docker.io/library/mongo:latest

Validation Rules

1. General

   • Version must be specified (v1 or v2)
   • Application name must be alphanumeric
   • At least one pod must be specified

2. Pods

   • Pod name must be alphanumeric
   • Pod type must be one of the supported types
   • Image must be a valid Docker image reference
   • Service ports must be unique across all pods

3. Volumes

   • Volume size must match pattern: ^\d+[KMGT]i?$ (e.g., "1Gi", "500Mi")
   • Mount paths must start with "/"

4. Environment Variables

   • Keys must be valid Unix environment variable names
   • Values are required but can be empty

Usage Example

import "github.com/Nexlayer/nexlayer-cli/pkg/template"

// Create a validator
validator := template.NewValidator()

// Create a template
yaml := &template.NexlayerYAML{
    Version: template.V2,
    Application: template.Application{
        Name: "myapp",
        Pods: []template.Pod{
            {
                Name:  "web",
                Type:  template.Frontend,
                Image: "myapp/web:latest",
            },
        },
    },
}

// Validate the template
if err := validator.Validate(yaml); err != nil {
    log.Fatal(err)
}

Best Practices

1. Always use the validator before processing templates
2. Use default images and configurations when possible
3. Follow the standard template structure
4. Keep pod names short but descriptive
5. Use semantic versioning for images

Documentation

Index

• Variables
• type Application
• type EnvVar
• type NexlayerYAML
• type Pod
• type PodType
• type Port
• type RegistryLogin
• type Secret
• type Validator
  • func NewValidator() *Validator
  • func (v *Validator) Validate(yaml *NexlayerYAML) error
• type Volume

Variables

var DefaultEnvVars = map[PodType][]EnvVar{
	Frontend: {
		{Key: "REACT_APP_API_URL", Value: "http://CANDIDATE_DEPENDENCY_URL_0"},
		{Key: "NODE_ENV", Value: "production"},
	},
	Backend: {
		{Key: "PORT", Value: "8080"},
		{Key: "DATABASE_URL", Value: "postgresql://CANDIDATE_DEPENDENCY_URL_1:5432/db"},
	},
	Postgres: {
		{Key: "POSTGRES_USER", Value: "postgres"},
		{Key: "POSTGRES_DB", Value: "postgres"},
	},
	MongoDB: {
		{Key: "MONGO_INITDB_ROOT_USERNAME", Value: "root"},
	},
}

DefaultEnvVars provides common environment variables for different pod types

var DefaultPorts = map[PodType][]Port{

	React: {
		{ContainerPort: 3000, ServicePort: 80, Name: "web"},
	},
	NextJS: {
		{ContainerPort: 3000, ServicePort: 80, Name: "web"},
	},
	Vue: {
		{ContainerPort: 8080, ServicePort: 80, Name: "web"},
	},

	FastAPI: {
		{ContainerPort: 8000, ServicePort: 8000, Name: "api"},
	},
	Express: {
		{ContainerPort: 3000, ServicePort: 3000, Name: "api"},
	},
	Django: {
		{ContainerPort: 8000, ServicePort: 8000, Name: "api"},
	},

	Postgres: {
		{ContainerPort: 5432, ServicePort: 5432, Name: "db"},
	},
	MongoDB: {
		{ContainerPort: 27017, ServicePort: 27017, Name: "db"},
	},
	Redis: {
		{ContainerPort: 6379, ServicePort: 6379, Name: "cache"},
	},

	Ollama: {
		{ContainerPort: 11434, ServicePort: 11434, Name: "llm"},
	},
	Jupyter: {
		{ContainerPort: 8888, ServicePort: 8888, Name: "notebook"},
	},
}

DefaultPorts maps pod types to their default port configurations

var DefaultVolumes = map[PodType][]struct {
	Name      string
	Size      string
	MountPath string
}{
	Postgres: {
		{
			Name:      "data",
			Size:      "1Gi",
			MountPath: "/var/lib/postgresql/data",
		},
	},
	MongoDB: {
		{
			Name:      "data",
			Size:      "1Gi",
			MountPath: "/data/db",
		},
	},
	Redis: {
		{
			Name:      "data",
			Size:      "1Gi",
			MountPath: "/data",
		},
	},
}

DefaultVolumes defines standard volume configurations for stateful pods

Types

type Application

type Application struct {
	Name          string         `yaml:"name" validate:"required,appname"` // lowercase, alphanumeric, '-', or '.'
	URL           string         `yaml:"url,omitempty" validate:"omitempty,url"`
	RegistryLogin *RegistryLogin `yaml:"registryLogin,omitempty" validate:"omitempty"`
	Pods          []Pod          `yaml:"pods" validate:"required,min=1,dive"`
}

Application represents a Nexlayer application configuration

type EnvVar

type EnvVar struct {
	Key   string `yaml:"key" validate:"required,envvar"`
	Value string `yaml:"value" validate:"required"`
}

EnvVar represents an environment variable

type NexlayerYAML

type NexlayerYAML struct {
	Application Application `yaml:"application" validate:"required"`
}

NexlayerYAML represents a complete Nexlayer application template

type Pod

type Pod struct {
	Name    string   `yaml:"name" validate:"required,podname"` // lowercase, alphanumeric, '-', or '.'
	Type    PodType  `yaml:"type" validate:"required,podtype"`
	Path    string   `yaml:"path,omitempty" validate:"omitempty,startswith=/"`
	Image   string   `yaml:"image" validate:"required,image"` // Full image URL including registry and tag
	Volumes []Volume `yaml:"volumes,omitempty" validate:"omitempty,dive"`
	Secrets []Secret `yaml:"secrets,omitempty" validate:"omitempty,dive"`
	Vars    []EnvVar `yaml:"vars,omitempty" validate:"omitempty,dive"`
	Ports   []Port   `yaml:"ports" validate:"required,dive"`
}

Pod represents a container configuration

type PodType

type PodType string

PodType represents the type of a pod

const (
	// Frontend pod types
	Frontend PodType = "frontend"
	React    PodType = "react"
	NextJS   PodType = "nextjs"
	Vue      PodType = "vue"

	// Backend pod types
	Backend PodType = "backend"
	Express PodType = "express"
	Django  PodType = "django"
	FastAPI PodType = "fastapi"
	Node    PodType = "node"
	Python  PodType = "python"
	Golang  PodType = "golang"
	Java    PodType = "java"

	// Database pod types
	Database   PodType = "database"
	MongoDB    PodType = "mongodb"
	Postgres   PodType = "postgres"
	Redis      PodType = "redis"
	MySQL      PodType = "mysql"
	Clickhouse PodType = "clickhouse"

	// Message Queue types
	RabbitMQ PodType = "rabbitmq"
	Kafka    PodType = "kafka"

	// Storage types
	Minio   PodType = "minio"
	Elastic PodType = "elasticsearch"

	// Web Server types
	Nginx   PodType = "nginx"
	Traefik PodType = "traefik"

	// AI/ML pod types
	LLM      PodType = "llm"
	Ollama   PodType = "ollama"
	HFModel  PodType = "huggingface"
	VertexAI PodType = "vertexai"
	Jupyter  PodType = "jupyter"
)

type Port

type Port struct {
	ContainerPort int    `yaml:"containerPort" validate:"required,gt=0,lt=65536"`
	ServicePort   int    `yaml:"servicePort" validate:"required,gt=0,lt=65536"`
	Name          string `yaml:"name" validate:"required,portname"` // web, api, db, etc
}

Port represents a port configuration

type RegistryLogin

type RegistryLogin struct {
	Registry            string `yaml:"registry" validate:"required,hostname"`
	Username            string `yaml:"username" validate:"required"`
	PersonalAccessToken string `yaml:"personalAccessToken" validate:"required"`
}

RegistryLogin represents private registry authentication

type Secret

type Secret struct {
	Name      string `yaml:"name" validate:"required,secretname"` // lowercase, alphanumeric, '-'
	Data      string `yaml:"data" validate:"required"`            // Raw or Base64-encoded secret content
	MountPath string `yaml:"mountPath" validate:"required,startswith=/"`
	FileName  string `yaml:"fileName" validate:"required,filename"`
}

Secret represents encrypted credentials or config files

type Validator

type Validator struct{}

Validator handles all template validation

func NewValidator

func NewValidator() *Validator

NewValidator creates a new template validator

func (*Validator) Validate

func (v *Validator) Validate(yaml *NexlayerYAML) error

Validate validates a complete template

type Volume

type Volume struct {
	Name      string `yaml:"name" validate:"required,volumename"` // lowercase, alphanumeric, '-'
	Size      string `yaml:"size" validate:"required,volumesize"` // e.g., "1Gi", "500Mi"
	MountPath string `yaml:"mountPath" validate:"required,startswith=/"`
}

Volume represents a persistent storage volume