pctl/pctl.yml.example at main · deviantony/pctl · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
# pctl Configuration File Example
# Copy this file to pctl.yml and customize the values for your environment

# Portainer instance URL
# The URL of your Portainer instance (e.g., https://portainer.example.com or https://192.168.1.100:9443)
portainer_url: https://portainer.example.com

# Portainer API token
# Generate this token in Portainer: Settings > API Keys > Add access token
# Token should start with 'ptr_' (e.g., ptr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)
api_token: ptr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Portainer environment ID
# The ID of the environment/endpoint where you want to deploy your stack
# You can find this by running 'pctl init' and selecting from the list, or by checking Portainer's API
environment_id: 1

# Stack name
# The name for your Docker Compose stack in Portainer
# Default: pctl_<project-folder-name> (e.g., pctl_myproject)
stack_name: pctl_myproject

# Docker Compose file path
# Path to your Docker Compose file relative to the current directory
# Default: docker-compose.yml
compose_file: docker-compose.yml

# TLS certificate verification
# Set to true to skip TLS certificate verification (recommended for self-hosted Portainer)
# Set to false to enforce TLS certificate verification (for production with valid certificates)
# Default: true
skip_tls_verify: true

# Build configuration (optional)
# Controls how Docker images are built when using 'build:' directives in compose files
# This section is only used when your compose file contains services with 'build:' directives
build:
  # Build mode: 'remote-build' (default) or 'load'
  # remote-build: builds on the remote Docker engine via Portainer proxy (bandwidth efficient)
  #   - Best for: Most use cases, minimal bandwidth usage, leverages remote build cache
  #   - Use when: Remote has good internet access to pull base images
  # load: builds locally and uploads image tars to remote engine
  #   - Best for: Air-gapped environments, poor remote internet, specific local build requirements
  #   - Use when: Remote cannot pull base images or you need local build tools
  mode: remote-build

  # Parallel builds: 'auto' (derive from remote CPU) or a number
  # 'auto': Automatically determines parallelism based on remote Docker engine CPU count
  # Number: Explicitly set the number of concurrent builds (e.g., 2, 4, 8)
  # Use 'auto' for optimal performance, or set a number to limit resource usage
  parallel: auto

  # Image tag format template
  # Available variables: {{stack}}, {{service}}, {{hash}}, {{timestamp}}
  # {{stack}}: Replaced with the stack name from pctl.yml
  # {{service}}: Replaced with the service name from compose file
  # {{hash}}: Replaced with content hash (enables build skipping when unchanged)
  # {{timestamp}}: Replaced with Unix timestamp (always unique, forces rebuild)
  # Examples:
  #   "pctl-{{stack}}-{{service}}:{{hash}}" - Default, enables caching
  #   "{{stack}}/{{service}}:{{timestamp}}" - Always unique, no caching
  tag_format: "pctl-{{stack}}-{{service}}:{{hash}}"

  # Target platforms for load mode (when building locally)
  # Only used when mode is 'load' - specifies which platforms to build for
  # Common values: ["linux/amd64"], ["linux/arm64"], ["linux/amd64", "linux/arm64"]
  # Use ["linux/amd64"] for most servers, add arm64 for ARM-based servers
  platforms: ["linux/amd64"]

  # Global build arguments (merged with compose build.args)
  # These build args are added to ALL services with build directives
  # Use for: Common environment variables, shared secrets, global configuration
  # Example: { "NODE_ENV": "production", "BUILD_VERSION": "1.0.0" }
  extra_build_args: {}

  # Force rebuild even if content hash indicates no change (also disables cache)
  # Set to true to always rebuild images and pass --no-cache to builds
  # Use when: You want completely fresh builds or to debug build issues
  # Note: This defeats the purpose of content-hash based caching and may be slower
  force_build: false

  # Warning threshold for context tar or image size (MB)
  # pctl will emit a warning if the build context or image exceeds this size
  # Use to: Monitor and optimize build context size, avoid accidentally including large files
  # Recommended: 50-100MB for most projects, increase for projects with large dependencies
  warn_threshold_mb: 50

# Example configurations for different scenarios:

# Production setup with valid certificates:
# portainer_url: https://portainer.company.com
# api_token: ptr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# environment_id: 1
# stack_name: pctl_production_app
# compose_file: docker-compose.prod.yml
# skip_tls_verify: false

# Development setup with self-signed certificates:
# portainer_url: https://192.168.1.100:9443
# api_token: ptr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# environment_id: 2
# stack_name: pctl_dev_app
# compose_file: docker-compose.dev.yml
# skip_tls_verify: true

# Local development with custom compose file:
# portainer_url: https://localhost:9443
# api_token: ptr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# environment_id: 1
# stack_name: pctl_local_test
# compose_file: docker-compose.local.yml
# skip_tls_verify: true