Productify

Appearance

Project Configuration ​

The ProductifyFW CLI supports project-level configuration through a project.yaml file. This file stores project metadata, CI/CD settings, and environment configurations, allowing you to run CLI commands without repetitive flags.

Overview ​

The project.yaml file is located in your project root directory and contains:

  • Project metadata (name, version, ID)
  • CI/CD configuration (language, registry, Docker image)
  • Environment/tenant mappings

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: "proj_123" # Optional: ProductifyFW project ID
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/Tenants
environments:
  production:
    tenant_id: "tenant_abc"
    application_id: "app_xyz"
    name: "Production"
    description: "Production environment"
  staging:
    tenant_id: "tenant_def"
    application_id: "app_uvw"
    name: "Staging"
    description: "Staging environment"

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/workflows/ci.yml

With project.yaml, just run:

bash
pfy ci update --output .github/workflows/ci.yml

All parameters are 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 --output .github/workflows/ci.yml

Managing Environments ​

The environments section maps ProductifyFW tenants to deployment environments. This is useful for multi-tenant applications where different tenants have different configurations.

Adding Environments ​

Edit project.yaml manually:

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

Use Cases ​

  • Multi-tenant SaaS: Map each customer to a tenant ID
  • Environment promotion: Track which application version is in each environment
  • Deployment targeting: Specify deployment targets in CI/CD

Best Practices ​

Version Control ​

DO 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 ​

DON'T 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 ​

Update the file directly or re-run pfy init with new values:

bash
# Update CI type to GitLab
pfy init --ci-type gitlab

Note: This will preserve existing values not specified in flags.

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

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 --output .github/workflows/prod-ci.yml

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 ​