Productify

Appearance

Project Configuration ​

project.yaml is a small file in the root of your repository. It stores the project's name and version, the settings pfy ci update needs, and environment aliases that let deploy commands refer to a Manager deployment by a short name. Commands read it from the current directory, so you can leave out flags you would otherwise repeat.

Overview ​

project.yaml holds three groups of keys:

  • Project metadata: project_id, project_name, version
  • CI settings under ci:: type, language, registry, image_name, nomad_file
  • Environment aliases under environments:

These are the only keys the CLI reads; anything else is ignored and dropped the next time the CLI rewrites the file.

Creating a Project Configuration ​

Using pfy init ​

Initialize a new project configuration:

bash
pfy init --name my-app --language go --ci-type github

This creates a project.yaml file with auto-detected settings:

yaml
project_name: my-app
version: 0.1.0
ci:
  type: github
  language: go
  registry: ghcr.io
  image_name: my-app

Flags ​

  • --name: Project name (defaults to current directory name)
  • --language: Project language (go or node, auto-detected from go.mod/package.json)
  • --ci-type: CI/CD platform (github or gitlab, defaults to github)
  • --registry: Docker registry URL (defaults to ghcr.io)

Auto-Detection ​

If you don't specify flags, pfy init will:

  • Use the current directory name as project name
  • Detect language from go.mod (Go) or package.json (Node.js)
  • Use sensible defaults for registry and CI type

Configuration Schema ​

yaml
# Project metadata
project_id: "01234567-89ab-cdef-0123-456789abcdef" # Optional: ProductifyFW project ID (UUID)
project_name: "my-application" # Required: Project name
version: "1.0.0" # Optional: Application version

# CI/CD configuration
ci:
  type: "github" # "github" or "gitlab"
  language: "go" # "go" or "node"
  registry: "ghcr.io" # Docker registry URL
  image_name: "my-app" # Docker image name
  nomad_file: "nomad/manager.nomad" # Optional: Path to Nomad job file

# Environments — local aliases resolving a name to server-side IDs
environments:
  production:
    tenant_id: "tenant_abc" # Optional: tenant this alias targets
    application_id: "app_xyz" # Application the alias's deploy/render commands act on
    environment_id: "env_123" # Server-side Environment entity the alias resolves to
    deployment_id: "dep_456" # Cached (application, environment) Deployment ID
    name: "Production"
    description: "Production environment"
  staging:
    tenant_id: "tenant_def"
    application_id: "app_uvw"
    environment_id: "env_789"
    name: "Staging"
    description: "Staging environment"

All environment-alias fields are optional. environment_id links the alias to the server Environment entity; deployment_id caches the resolved deployment (the shared one; commands passed --tenant deliberately bypass it). tenant_id is optional. See env for the commands that write these fields.

The example above uses short placeholder IDs. Real values are UUIDs.

Using Project Configuration ​

Priority Order ​

When you run CLI commands, configuration values are resolved in this order:

  1. CLI flags (highest priority)
  2. project.yaml values
  3. Auto-detection (e.g., from go.mod)
  4. Defaults (lowest priority)

Example: CI/CD Templates ​

Without project.yaml, you need to specify all parameters:

bash
pfy ci update \
  --type github \
  --language go \
  --project-name my-app \
  --registry ghcr.io \
  --image-name my-app \
  --output .github

With project.yaml, just run:

bash
pfy ci update

Every parameter is read from project.yaml.

Overriding Values ​

You can still override specific values with flags:

bash
# Use different registry for this run
pfy ci update --registry docker.io

Managing Environments ​

The environments section gives a short name (such as prod) to a set of Manager IDs. Deploy and render commands take that name with --env prod and resolve it to the right application and deployment, so you never paste UUIDs on the command line.

Adding Environments ​

Use the pfy env command family instead of hand-editing:

bash
# Record a local alias, resolving tenant/application slugs to IDs
pfy env add customer-a --tenant customer-a --application web-app --name "Customer A Production"

# Or link an alias to a server-side Environment entity
pfy env link prod --environment-id <env-id> --app <application-id>

pfy sync also seeds one alias per tenant of the project automatically.

You can still edit project.yaml directly:

yaml
environments:
  customer-a:
    tenant_id: "tenant_123"
    application_id: "app_456"
    name: "Customer A Production"
    description: "Production environment for Customer A"

Best Practices ​

Version Control ​

Commit project.yaml to version control:

bash
git add project.yaml
git commit -m "Add project configuration"

This ensures all team members have the same configuration.

Security ​

Do not put secrets in project.yaml:

yaml
# [NO] WRONG - never put tokens in project.yaml
ci:
  registry_token: "super_secret_token"

Use environment variables or ~/.pfy/config.yaml for authentication tokens.

Updating Configuration ​

Edit project.yaml directly to change settings. pfy init refuses to run if project.yaml already exists, so it cannot be used to update an existing configuration.

Example Workflows ​

Go Project with GitHub Actions ​

bash
# Initialize project
pfy init --name my-go-service --language go

# Generate CI/CD templates
pfy ci update

# Files created:
# - .github/workflows/ci.yml
# - .github/workflows/release.yml
# - Dockerfile

See ci for what each generated pipeline contains; Go and Node.js pipelines differ.

Node.js Project with GitLab CI ​

bash
# Initialize project
pfy init --name my-node-api --language node --ci-type gitlab

# Generate CI/CD templates
pfy ci update

# Files created:
# - .gitlab-ci.yml
# - Dockerfile

Multi-Registry Setup ​

bash
# Development: use Docker Hub
pfy init --registry docker.io --name myapp

# Production: override with GitHub Container Registry
pfy ci update --registry ghcr.io

Troubleshooting ​

Command Ignores project.yaml ​

Ensure you're running commands from the project root where project.yaml is located. The CLI looks for ./project.yaml in the current directory.

Auto-Detection Not Working ​

If language auto-detection fails:

  1. Check that go.mod or package.json exists
  2. Explicitly specify --language flag
  3. Update project.yaml manually

Configuration Not Updating ​

pfy init will fail if project.yaml already exists. To update:

  • Edit project.yaml manually, or
  • Delete project.yaml and run pfy init again

See Also ​