Blueprints - Pangolin Docs

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.

Blueprints let you define Pangolin resources as code. Instead of configuring every site, target, and access rule manually in the dashboard, you describe the desired state in YAML or container labels and let Pangolin apply it consistently. Use blueprints when you want:

Repeatable rollouts across many sites
Version control for infrastructure and access settings
A source of truth that can be reviewed, templated, and automated

Some features in this documentation are marked with (EE), which means they require Enterprise Edition.

Blueprint Mental Model

A blueprint can contain up to three top-level sections:

public-resources: Internet-facing HTTP, TCP, or UDP resources
private-resources: Client-only access to hosts or CIDR ranges
sites: Site-level settings such as container label discovery

public-resources:
  <resource_key>:
    ...

private-resources:
  <resource_key>:
    ...

sites:
  <site_key>:
    ...

Think of the resource key as your stable ID inside the blueprint. The fields under that key describe what Pangolin should create or maintain.

Choose A Format

Pangolin supports two blueprint formats:

YAML

Use YAML when you want a readable file that can be committed to git, applied through Newt, pasted into the UI, or sent through the API.

Container Labels

Use container labels when the resource definition should live inside your Compose stack. This is especially useful when a container and its Pangolin resource should be managed together.

How YAML Blueprints Are Applied

UI

Paste YAML into Settings > Blueprints in the Pangolin dashboard.

Newt

Run Newt with --blueprint-file to keep the file declarative and continuously applied:

newt --blueprint-file /path/to/blueprint.yaml <other-args>

If you only want a one-time bootstrap during provisioning, use --provisioning-blueprint-file instead.

API

Apply a blueprint through the Pangolin API with an API key. See the API documentation.PUT /org/{orgId}/blueprint

{
  "blueprint": "base64-encoded-json-content"
}

Python example

CLI

Apply a blueprint directly from the Pangolin CLI when you want a one-off apply from a terminal, CI job, or local automation.Using your logged-in user accountFirst log in and select the organization you want the blueprint applied to:

pangolin login
pangolin select org --org <org_id>

Then apply the file:

pangolin apply blueprint --file /path/to/blueprint.yaml

The CLI uses your active account and selected organization. You can optionally set the saved blueprint name:

pangolin apply blueprint --file /path/to/blueprint.yaml --name production

Using an Integration API keyFor non-interactive automation, pass an Integration API key, API endpoint, and organization ID together:

pangolin apply blueprint \
  --file /path/to/blueprint.yaml \
  --api-key <api_key_id.api_key_secret> \
  --endpoint https://api.example.com \
  --org <org_id>

For Pangolin Cloud, use https://api.pangolin.net as the endpoint. For self-hosted Pangolin, use your API host, for example https://api.your-domain.com. See Integration API for creating API keys and enabling the API on self-hosted deployments.You can also pipe a blueprint through stdin. When using stdin, provide --name because there is no filename to derive it from:

render-blueprint | pangolin apply blueprint --file - --name production

--blueprint-file in Newt and container labels behave as an ongoing source of truth. Dashboard edits can be overwritten the next time the blueprint is applied. UI, API, and CLI applies are typically one-off operations.

Quick Start YAML Example

This example shows all three top-level sections in one file:

public-resources:
  web-app:
    name: Web App
    protocol: http
    full-domain: app.example.com
    auth:
      sso-enabled: true
      whitelist-users:
        - admin@example.com
    targets:
      - site: my-site
        hostname: app
        port: 8080
        method: http
        healthcheck:
          hostname: app
          port: 8080
          path: /health

private-resources:
  ssh-host:
    name: SSH Host
    mode: host
    sites:
      - my-site
    destination: 192.168.1.10
    tcp-ports: "22"
    roles:
      - DevOps

sites:
  my-site:
    name: My Site
    docker-socket-enabled: true

Public Resources

Public resources expose services through Pangolin.

Use http for websites, APIs, and dashboards
Use tcp or udp for raw public services bound to a port on the Pangolin server

HTTP Resource Example

public-resources:
  app:
    name: App
    protocol: http
    full-domain: app.example.com
    host-header: app.internal
    tls-server-name: app.internal
    headers:
      - name: X-Env
        value: production
    rules:
      - action: allow
        match: country
        value: US
      - action: deny
        match: path
        value: /admin
    auth:
      sso-enabled: true
      whitelist-users:
        - admin@example.com
    targets:
      - site: my-site
        hostname: app
        port: 8080
        method: http

When applying a blueprint via Newt (using --blueprint-file or container labels), site on each target is optional. If omitted, the target is assigned to the site of the Newt that applied the blueprint.

Raw TCP Or UDP Example

public-resources:
  mqtt:
    name: Mosquitto MQTT
    protocol: tcp
    proxy-port: 1883
    targets:
      - site: my-site
        hostname: mqtt-server
        port: 1883

For raw resources:

proxy-port is required
Target method must not be set
auth is not supported

Targets-Only Resources

A public resource can contain only targets. This is useful when you want to add or manage targets for an existing resource definition without repeating all resource-level fields.

public-resources:
  extra-targets:
    targets:
      - site: secondary-site
        hostname: app-2
        port: 8080
        method: http
      - site: tertiary-site
        hostname: app-3
        port: 8080
        method: http

When a resource is targets-only, name and protocol are not required.

Authentication Example

Authentication is configured inside auth and is supported only for HTTP resources.

public-resources:
  secure-app:
    name: Secure App
    protocol: http
    full-domain: secure.example.com
    auth:
      pincode: 123456
      password: strong-password
      basic-auth:
        user: demo
        password: change-me
      sso-enabled: true
      sso-roles:
        - Member
      sso-users:
        - user@example.com
      whitelist-users:
        - admin@example.com

Maintenance Page (EE)

The maintenance object lets you present a maintenance page for a public HTTP resource.

public-resources:
  app:
    name: App
    protocol: http
    full-domain: app.example.com
    maintenance:
      enabled: true
      type: automatic
      title: Scheduled Maintenance
      message: We are upgrading the service.
      estimated-time: 2 hours
    targets:
      - site: my-site
        hostname: app
        port: 8080
        method: http

Maintenance type values:

forced: Always show the maintenance page
automatic: Show it only when all targets are unhealthy or the sites are offline

Private Resources

Private resources define what Pangolin clients can reach after they connect to your organization.

Use mode: host for a single host or DNS name
Use mode: cidr for an entire network range
Use mode: http to expose an internal HTTP endpoint to clients via a private domain

When applying a blueprint via Newt (using --blueprint-file or container labels), sites is optional. If omitted, the resource is assigned to the site of the Newt that applied the blueprint.

private-resources:
  internal-net:
    name: Internal Network
    mode: cidr
    destination: 10.0.0.0/24
    sites:
      - my-site
    tcp-ports: "22,443,8000-9000"
    udp-ports: "53,123"
    disable-icmp: false
    alias: "*.internal.example.com"
    roles:
      - Developer
    users:
      - user@example.com
    machines:
      - machine-id-1

  internal-app:
    name: Internal App
    mode: http
    destination: 10.0.0.5
    destination-port: 8080
    sites:
      - my-site
    full-domain: app.internal.example.com
    ssl: true
    scheme: https
    roles:
      - Member

Container Labels Format

Container labels are the same blueprint schema flattened into dot-separated keys:

Start every label with pangolin.
Keep the same object path as YAML
Use array indexes for lists, such as [0]

Example YAML:

public-resources:
  my-app:
    headers:
      - name: X-Env
        value: prod

Equivalent Compose labels:

labels:
  - pangolin.public-resources.my-app.headers[0].name=X-Env
  - pangolin.public-resources.my-app.headers[0].value=prod

Container labels are continuously applied. Treat the Compose file as the source of truth because dashboard edits can be overwritten.

Enable Container Label Discovery

To use container labels, Newt must be able to read the Docker socket:

newt --docker-socket /var/run/docker.sock <other-args>

Or with an environment variable:

DOCKER_SOCKET=/var/run/docker.sock

Docker Compose Example

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - NEWT_ID=h1rbsgku89wf9z3
      - NEWT_SECRET=z7g54mbcwkglpx1aau9gb8mzcccoof2fdbs97keoakg2pp5z
      - DOCKER_SOCKET=/var/run/docker.sock

  nginx1:
    image: nginxdemos/hello
    container_name: nginx1
    labels:
      - pangolin.public-resources.nginx.name=nginx
      - pangolin.public-resources.nginx.full-domain=nginx.fosrl.io
      - pangolin.public-resources.nginx.protocol=http
      - pangolin.public-resources.nginx.headers[0].name=X-Example-Header
      - pangolin.public-resources.nginx.headers[0].value=example-value
      - pangolin.public-resources.nginx.targets[0].method=http
      - pangolin.public-resources.nginx.targets[0].path=/path
      - pangolin.public-resources.nginx.targets[0].path-match=prefix

  nginx2:
    image: nginxdemos/hello
    container_name: nginx2
    labels:
      - pangolin.public-resources.nginx.targets[1].method=http
      - pangolin.public-resources.nginx.targets[1].hostname=nginx2
      - pangolin.public-resources.nginx.targets[1].port=80

networks:
  default:
    name: pangolin_default

This creates a single Pangolin resource with multiple targets:

Container Label Behavior

Automatic Discovery

If hostname or port are not set explicitly, Pangolin can detect them from the container configuration. The hostname typically defaults to the container name, and port detection is based on the container’s expose configuration.

Site Assignment

If no site is specified on a target (public resource) or on a private resource, it is assigned to the site of the Newt that applied the blueprint — whether through container labels or --blueprint-file.

Merged Configuration

Labels from multiple containers can be merged into one logical resource, which is useful when different containers contribute different targets.

Configuration Reference

Use this section when you need the full schema. The order below mirrors the blueprint structure rather than the dashboard UI.

Top-Level Object

public-resources:
  app:
    name: App
    protocol: http
    full-domain: app.example.com
    targets:
      - hostname: app
        port: 80
        method: http

private-resources:
  ssh-host:
    name: SSH Host
    mode: host
    sites:
      - my-site
    destination: 192.168.1.10
    tcp-ports: "22"

sites:
  my-site:
    name: My Site
    docker-socket-enabled: true

Show Top-level object reference

public-resources

object

Public proxy resources keyed by resource ID.YAML: public-resources: { web-app: { ... } }
Container label: pangolin.public-resources.web-app.name=Web App

private-resources

object

Private resources keyed by resource ID.YAML: private-resources: { internal-net: { ... } }
Container label: pangolin.private-resources.internal-net.mode=cidr

sites

object

Site-level settings keyed by site ID.YAML: sites: { my-site: { name: My Site } }
Container label: pangolin.sites.my-site.name=My Site

Show Site object

name

string

required

Display name for the site.YAML: name: My Site
Container label: pangolin.sites.my-site.name=My Site

docker-socket-enabled

boolean

Enables blueprint discovery from container labels for that site.Default: trueYAML: docker-socket-enabled: true
Container label: pangolin.sites.my-site.docker-socket-enabled=true

Public Resource Object (`public-resources`)

public-resources:
  web-app:
    name: Web App
    protocol: http
    full-domain: app.example.com
    enabled: true
    host-header: internal.example.local
    tls-server-name: internal.example.local
    headers:
      - name: X-Env
        value: prod
    rules:
      - action: allow
        match: country
        value: US
      - action: deny
        match: region
        value: 019
    auth:
      pincode: 123456
      sso-enabled: true
      whitelist-users:
        - admin@example.com
    maintenance:
      enabled: true
      type: automatic
    targets:
      - site: my-site
        hostname: app
        port: 8080
        method: http
        path: /
        path-match: prefix
        rewrite-path: /
        rewrite-match: prefix
        healthcheck:
          hostname: app
          port: 8080
          path: /health

Show Public resource reference

<resource_key>

object

A single public resource definition.

Show Resource fields

name

string

Human-readable resource name. Required unless the resource is targets-only.YAML: name: Web App
Container label: pangolin.public-resources.web-app.name=Web App

protocol

string

Resource type.Options: http, tcp, udpYAML: protocol: http
Container label: pangolin.public-resources.web-app.protocol=http

ssl

boolean

Optional SSL/TLS flag present in the schema.YAML: ssl: true
Container label: pangolin.public-resources.web-app.ssl=true

full-domain

string

Public hostname for HTTP resources. Required when protocol: http.YAML: full-domain: app.example.com
Container label: pangolin.public-resources.web-app.full-domain=app.example.com

proxy-port

integer

Public port for raw TCP or UDP resources. Required when protocol is tcp or udp.YAML: proxy-port: 3000
Container label: pangolin.public-resources.raw-api.proxy-port=3000

enabled

boolean

Disables the resource without removing it.YAML: enabled: true
Container label: pangolin.public-resources.web-app.enabled=true

host-header

string

Overrides the upstream Host header sent to the target.YAML: host-header: internal.example.local
Container label: pangolin.public-resources.web-app.host-header=internal.example.local

tls-server-name

string

Overrides the TLS SNI hostname used for upstream TLS connections.YAML: tls-server-name: internal.example.local
Container label: pangolin.public-resources.web-app.tls-server-name=internal.example.local

headers

array of objects

Static headers added to proxied requests.Container labels for arrays must include an index ([0], [1], …).YAML: headers: [{ name: X-Env, value: prod }]
Container label: pangolin.public-resources.web-app.headers[0].name=X-Env

Show Header object

name

string

required

Header name.YAML: name: X-Env
Container label: pangolin.public-resources.web-app.headers[0].name=X-Env

value

string

required

Header value.YAML: value: prod
Container label: pangolin.public-resources.web-app.headers[0].value=prod

rules

array of objects

Ordered access rules for public resources.Container labels for arrays must include an index ([0], [1], …).YAML: rules: [{ action: allow, match: country, value: US }]
Container label: pangolin.public-resources.web-app.rules[0].action=allow

Show Rule object

action

string

required

What Pangolin should do when the rule matches.Options: allow, deny, passYAML: action: allow
Container label: pangolin.public-resources.web-app.rules[0].action=allow

match

string

required

Match type for the rule.Options: cidr, path, ip, country, asn, regionYAML: match: country
Container label: pangolin.public-resources.web-app.rules[0].match=country

value

string

required

Value to compare against, such as an IP, CIDR, path, country code, ASN, or region.YAML: value: US
Container label: pangolin.public-resources.web-app.rules[0].value=US

priority

integer

Explicit rule priority. If omitted, priority is assigned from the rule order.YAML: priority: 10
Container label: pangolin.public-resources.web-app.rules[0].priority=10

auth

object

Authentication settings for HTTP resources. Not allowed for tcp or udp.

Show Auth object

pincode

number

Numeric PIN required before access is granted.YAML: pincode: 123456
Container label: pangolin.public-resources.web-app.auth.pincode=123456

password

string

Shared password gate for the resource.YAML: password: super-secret
Container label: pangolin.public-resources.web-app.auth.password=super-secret

sso-enabled

boolean

Enables Pangolin sign-in for the resource.YAML: sso-enabled: true
Container label: pangolin.public-resources.web-app.auth.sso-enabled=true

sso-roles

array of strings

Roles allowed through SSO.Container labels for arrays must include an index ([0], [1], …).YAML: sso-roles: [Member]
Container label: pangolin.public-resources.web-app.auth.sso-roles[0]=Member

sso-users

array of strings

Specific user identifiers allowed through SSO.Container labels for arrays must include an index ([0], [1], …).YAML: sso-users: [user@example.com]
Container label: pangolin.public-resources.web-app.auth.sso-users[0]=user@example.com

whitelist-users

array of strings

Whitelisted emails or patterns allowed for email-based access flows.Container labels for arrays must include an index ([0], [1], …).YAML: whitelist-users: [admin@example.com]
Container label: pangolin.public-resources.web-app.auth.whitelist-users[0]=admin@example.com

Identity provider ID to redirect to automatically.YAML: auto-login-idp: 1
Container label: pangolin.public-resources.web-app.auth.auto-login-idp=1

basic-auth

object

HTTP basic auth settings.

Show Basic auth

user

string

required

Basic auth username.YAML: user: demo
Container label: pangolin.public-resources.web-app.auth.basic-auth.user=demo

password

string

required

Basic auth password.YAML: password: change-me
Container label: pangolin.public-resources.web-app.auth.basic-auth.password=change-me

extendedCompatibility

boolean

Compatibility flag for basic auth behavior.Default: trueYAML: extendedCompatibility: true
Container label: pangolin.public-resources.web-app.auth.basic-auth.extendedCompatibility=true

maintenance

object

Maintenance page configuration for public resources (EE).YAML: maintenance: { enabled: true, type: forced }
Container label: pangolin.public-resources.web-app.maintenance.enabled=true

Show Maintenance object

enabled

boolean

Turns the maintenance page feature on for the resource.

type

string

When Pangolin should show the page.Options: forced, automatic

title

string

Main heading shown on the maintenance page.

message

string

Message shown to users while the resource is unavailable.

estimated-time

string

Optional estimate for when the service will return.

targets

array of objects

Backend destinations for the resource.Container labels for arrays must include an index ([0], [1], …).YAML: targets: [{ hostname: app, port: 8080, method: http }]
Container label: pangolin.public-resources.web-app.targets[0].hostname=app

Show Target object

site

string

Site that hosts the target. Optional when deploying from a Newt — if omitted, the target is assigned to the site of the Newt that applied the blueprint.YAML: site: my-site
Container label: pangolin.public-resources.web-app.targets[0].site=my-site

method

string

Upstream protocol for HTTP resources.Options: http, https, h2cYAML: method: http
Container label: pangolin.public-resources.web-app.targets[0].method=http

hostname

string

required

Target hostname or IP address.YAML: hostname: app
Container label: pangolin.public-resources.web-app.targets[0].hostname=app

port

integer

required

Target port.YAML: port: 8080
Container label: pangolin.public-resources.web-app.targets[0].port=8080

enabled

boolean

Disables the target without deleting it.YAML: enabled: true
Container label: pangolin.public-resources.web-app.targets[0].enabled=true

internal-port

integer

Internal port override used in container-oriented setups.YAML: internal-port: 8080
Container label: pangolin.public-resources.web-app.targets[0].internal-port=8080

path

string

Path condition used for HTTP routing.YAML: path: /
Container label: pangolin.public-resources.web-app.targets[0].path=/

path-match

string

Matching mode for path.Options: exact, prefix, regex

rewrite-path

string

Replacement path or prefix used during path rewriting.YAML: rewrite-path: /
Container label: pangolin.public-resources.web-app.targets[0].rewrite-path=/

rewritePath

string

Deprecated alias for rewrite-path.

rewrite-match

string

Rewrite mode.Options: exact, prefix, regex, stripPrefix

priority

integer

Target priority used in routing decisions.Range: 1-1000
Default: 100YAML: priority: 100
Container label: pangolin.public-resources.web-app.targets[0].priority=100

healthcheck

object

Health monitoring for the target.

Show Healthcheck object

hostname

string

required

Hostname or IP used for the health check.

port

integer

required

Port used for the health check.

enabled

boolean

Enables health checking for the target.

path

string

HTTP path to check, such as /health.

scheme

string

Scheme to use for the check.

mode

string

Health check mode supported by the schema.

interval

integer

Check interval while the target is healthy.

unhealthy-interval

integer

Check interval while the target is unhealthy.

unhealthyInterval

integer

Deprecated alias for unhealthy-interval.

timeout

integer

Timeout for each health check attempt.

headers

array of objects

Headers sent with the health check request.Container labels for arrays must include an index ([0], [1], …).YAML: headers: [{ name: X-Health-Check, value: true }]
Container label: pangolin.public-resources.web-app.targets[0].healthcheck.headers[0].name=X-Health-Check

Show Healthcheck header object

name

string

required

Header name.

value

string

required

Header value.

follow-redirects

boolean

Whether redirects should be followed.

followRedirects

boolean

Deprecated alias for follow-redirects.

method

string

HTTP method for the check request.

status

integer

Expected HTTP status code.

Private Resource Object (`private-resources`)

private-resources:
  internal-net:
    name: Internal Network
    mode: cidr
    sites:
      - my-site
    destination: 10.0.0.0/24
    tcp-ports: "22,443"
    udp-ports: "53"
    disable-icmp: false
    alias: "*.internal.example.com"
    roles:
      - Member
    users:
      - user@example.com
    machines:
      - machine-id-1

  internal-app:
    name: Internal App
    mode: http
    sites:
      - my-site
    destination: 10.0.0.5
    destination-port: 8080
    full-domain: app.internal.example.com
    ssl: true
    scheme: https

Show Private resource reference

<resource_key>

object

A single private resource definition.

Show Resource fields

name

string

required

Display name for the resource.YAML: name: Internal Network
Container label: pangolin.private-resources.internal-net.name=Internal Network

mode

string

required

Private resource type.Options: host, cidr, http

host: A single host or IP. If destination is a domain, alias is required.
cidr: An entire IPv4 or IPv6 CIDR range.
http: An internal HTTP endpoint exposed to clients via full-domain.

YAML: mode: cidr
Container label: pangolin.private-resources.internal-net.mode=cidr

sites

array of strings

Sites that host the resource. Optional when deploying from a Newt — if omitted, the resource is assigned to the site of the Newt that applied the blueprint.Container labels for arrays must include an index ([0], [1], …).YAML: sites: [my-site]
Container label: pangolin.private-resources.internal-net.sites[0]=my-site

site

string

deprecated

Deprecated. Use sites instead.YAML: site: my-site
Container label: pangolin.private-resources.internal-net.site=my-site

destination

string

required

Host, IP, or CIDR block the client should reach. The accepted format depends on mode:

host: a valid IPv4/IPv6 address, or a hostname/domain (when using a domain, alias must also be set)
cidr: a valid IPv4 or IPv6 CIDR block
http: a host or IP for the upstream HTTP endpoint

YAML: destination: 10.0.0.0/24
Container label: pangolin.private-resources.internal-net.destination=10.0.0.0/24

destination-port

integer

Upstream port for the destination. Typically used with mode: http to point at the internal HTTP endpoint’s port.YAML: destination-port: 8080
Container label: pangolin.private-resources.internal-app.destination-port=8080

full-domain

string

Internal domain used to expose an HTTP private resource to clients. Applies when mode: http.YAML: full-domain: app.internal.example.com
Container label: pangolin.private-resources.internal-app.full-domain=app.internal.example.com

ssl

boolean

Whether SSL/TLS should be used when serving the private HTTP resource.YAML: ssl: true
Container label: pangolin.private-resources.internal-app.ssl=true

scheme

string

Upstream scheme used by Pangolin to reach the destination for HTTP private resources.Options: http, httpsYAML: scheme: https
Container label: pangolin.private-resources.internal-app.scheme=https

tcp-ports

string

Allowed TCP ports or ranges. Use comma-separated values for multiple ports or ranges, such as 22,443,8000-9000 or * for all ports or leave empty for no ports.Default: *YAML: tcp-ports: "22,443"
Container label: pangolin.private-resources.internal-net.tcp-ports=22,443

udp-ports

string

Allowed UDP ports or ranges. Use comma-separated values for multiple ports or ranges, such as 22,443,8000-9000 or * for all ports or leave empty for no ports.Default: *YAML: udp-ports: "53"
Container label: pangolin.private-resources.internal-net.udp-ports=53

disable-icmp

boolean

Prevents ICMP traffic such as ping.Default: falseYAML: disable-icmp: false
Container label: pangolin.private-resources.internal-net.disable-icmp=false

alias

string

Internal DNS alias for the resource. Must be a fully qualified domain name and may include wildcards (*, ?), e.g. example.com, *.example.com, or host-0?.example.internal. Required when mode: host and destination is a domain.YAML: alias: "*.internal.example.com"
Container label: pangolin.private-resources.internal-net.alias=*.internal.example.com

roles

array of strings

Roles allowed to access the resource. The Admin role is reserved and cannot be listed here.Container labels for arrays must include an index ([0], [1], …).YAML: roles: [Member]
Container label: pangolin.private-resources.internal-net.roles[0]=Member

users

array of strings

Individual users allowed to access the resource.Container labels for arrays must include an index ([0], [1], …).YAML: users: [user@example.com]
Container label: pangolin.private-resources.internal-net.users[0]=user@example.com

machines

array of strings

Machine identities allowed to access the resource.Container labels for arrays must include an index ([0], [1], …).YAML: machines: [machine-id-1]
Container label: pangolin.private-resources.internal-net.machines[0]=machine-id-1

Validation Rules And Constraints

Core Rules

A public resource can be targets-only. In that case it may contain only targets, and name plus protocol are not required.
When protocol is http, the resource must have full-domain and each target must include method.
When protocol is tcp or udp, the resource must have proxy-port, targets must not include method, and auth is not allowed.
full-domain values must be unique across public resources.
proxy-port values must be unique per protocol within public-resources. TCP 3000 and UDP 3000 can coexist, but two TCP resources cannot both use 3000.
alias values must be unique across private resources in the blueprint.

Common Validation Errors

”Admin role cannot be included in sso-roles”

Admin is reserved and cannot be used in auth.sso-roles.

”Duplicate ‘full-domain’ values found”

Every public HTTP resource must have its own unique full-domain.

”Duplicate ‘proxy-port’ values found in public-resources”

Two public resources with the same protocol cannot reuse the same proxy-port.

”When protocol is ‘http’, all targets must have a ‘method’ field”

Each HTTP target must specify http, https, or h2c.

”When protocol is ‘tcp’ or ‘udp’, targets must not have a ‘method’ field”

Raw targets do not use HTTP methods.

”When protocol is ‘tcp’ or ‘udp’, ‘auth’ must not be provided”

Authentication settings apply only to HTTP public resources.

”Resource must either be targets-only or have both ‘name’ and ‘protocol’ fields”

Provide both fields for a full public resource definition, or remove everything except targets.

”Duplicate ‘alias’ values found in private-resources”

Private resource aliases must be unique within the blueprint.

”Destination must be a valid IP address or valid domain AND alias is required”

In host mode, the destination must be a valid host or IP. If you use a domain, provide alias as well.

”Destination must be a valid CIDR notation for cidr mode”

In cidr mode, destination must be a valid CIDR block such as 10.0.0.0/24.

”Admin role cannot be included in roles”

Admin is reserved and cannot be used in private resource roles.

About

Manage Pangolin

Self-host Pangolin

Development

Documentation Index

Try free on Pangolin Cloud

​Blueprint Mental Model

​Choose A Format

​YAML

​Container Labels

​How YAML Blueprints Are Applied

UI

Newt

API

CLI

​Quick Start YAML Example

​Public Resources

​HTTP Resource Example

​Raw TCP Or UDP Example

​Targets-Only Resources

​Authentication Example

​Maintenance Page (EE)

​Private Resources

​Container Labels Format

​Enable Container Label Discovery

​Docker Compose Example

​Container Label Behavior

Automatic Discovery

Site Assignment

Merged Configuration

​Configuration Reference

​Top-Level Object

​Public Resource Object (public-resources)

​Private Resource Object (private-resources)

​Validation Rules And Constraints

​Core Rules

​Common Validation Errors

​”Admin role cannot be included in sso-roles”

​”Duplicate ‘full-domain’ values found”

​”Duplicate ‘proxy-port’ values found in public-resources”

​”When protocol is ‘http’, all targets must have a ‘method’ field”

​”When protocol is ‘tcp’ or ‘udp’, targets must not have a ‘method’ field”

​”When protocol is ‘tcp’ or ‘udp’, ‘auth’ must not be provided”

​”Resource must either be targets-only or have both ‘name’ and ‘protocol’ fields”

​”Duplicate ‘alias’ values found in private-resources”

​”Destination must be a valid IP address or valid domain AND alias is required”

​”Destination must be a valid CIDR notation for cidr mode”

​”Admin role cannot be included in roles”

Blueprint Mental Model

Choose A Format

YAML

Container Labels

How YAML Blueprints Are Applied

Quick Start YAML Example

Public Resources

HTTP Resource Example

Raw TCP Or UDP Example

Targets-Only Resources

Authentication Example

Maintenance Page (EE)

Private Resources

Container Labels Format

Enable Container Label Discovery

Docker Compose Example

Container Label Behavior

Configuration Reference

Top-Level Object

Public Resource Object (`public-resources`)

Private Resource Object (`private-resources`)

Validation Rules And Constraints

Core Rules

Common Validation Errors

”Admin role cannot be included in sso-roles”

”Duplicate ‘full-domain’ values found”

”Duplicate ‘proxy-port’ values found in public-resources”

”When protocol is ‘http’, all targets must have a ‘method’ field”

”When protocol is ‘tcp’ or ‘udp’, targets must not have a ‘method’ field”

”When protocol is ‘tcp’ or ‘udp’, ‘auth’ must not be provided”

”Resource must either be targets-only or have both ‘name’ and ‘protocol’ fields”

”Duplicate ‘alias’ values found in private-resources”

”Destination must be a valid IP address or valid domain AND alias is required”

”Destination must be a valid CIDR notation for cidr mode”

”Admin role cannot be included in roles”