Deploy your first app

By the end of this guide you’ll have a running app at https://<app>.<owner>.proxifai.app with TLS, autoscaling, and a forge PR you can edit any time you want to change the deploy config.

The whole flow takes about a minute.

Prerequisites

• A ProxifAI account (run locally or on a hosted instance)
• A forge repo with either:
  • A Dockerfile at the repo root, or
  • A standard project file (package.json, go.mod, requirements.txt, Cargo.toml, Gemfile, pom.xml, build.gradle) — buildpacks handle these without a Dockerfile

That’s it. No .proxifai/config.yaml, no manifests to write — ProxifAI generates everything as a PR you review before merging.

Option 1: from the forge UI

1. Open any repo in the Code tab.
2. Click the Deploy button next to “Issues” / “Pull requests” / “Settings”.
3. Pick the base branch (defaults to main) and click Open deploy PR.
4. ProxifAI opens a PR titled chore(deploy): set up ProxifAI deploy for <app>. The PR adds:
   • k8s/base/ — Deployment, Service, Ingress, HPA, Kustomization
   • k8s/overlays/production/ — production patches (2 replicas)
   • .proxifai/config.yaml — minimal platform metadata (just the manifest path + build hints)
5. Review the diff. Edit anything you want directly in the PR.
6. Merge.

ProxifAI builds the image, pushes to the internal registry, applies the manifests. Within ~30 seconds you’ll see a deploy success event in your Inbox with the live URL.

Option 2: from the CLI

cd path/to/your/repo

# pfai picks up the forge URL from `git remote get-url origin` automatically.
pfai deploy

Output:

Opening Deploy PR for henry/billing on branch main...

✓ PR #142 opened: /henry/billing/pulls/142
  Once merged, your app will be live at:
    https://billing.henry.proxifai.app
  Review the manifests, then merge to deploy.

Useful flags:

pfai deploy --app billing-api          # override the app name
pfai deploy --branch develop           # target a non-main base branch
pfai deploy --repo acme/widgets        # deploy a repo other than $PWD

What’s in the PR

A typical first deploy adds 8 files. Here’s the structure:

k8s/
├── base/
│   ├── deployment.yaml      # 1 replica, 250m CPU / 256Mi memory
│   ├── service.yaml         # ClusterIP on port 80 → app port
│   ├── ingress.yaml         # *.proxifai.app host with auto-issued TLS
│   ├── hpa.yaml             # 1–5 replicas, 70% CPU target
│   └── kustomization.yaml
└── overlays/
    └── production/
        ├── kustomization.yaml
        └── replicas-patch.yaml  # bumps to 2 replicas
.proxifai/
└── config.yaml              # { manifests: ./k8s, build: { type: dockerfile } }

Everything inside k8s/ is standard Kubernetes. You can kubectl apply -k k8s/overlays/production/ it locally if you have a kubeconfig. Power users can edit it directly. Simpler users never look at it.

After merging

• First deploy URL appears in the PR comment from proxifai-bot and in your Inbox.
• Push to main auto-rebuilds and redeploys (via the forge push webhook).
• Open a PR and you get an automatic preview environment at https://pr-<N>-<repo>.<owner>.proxifai.app.

Editing the deploy config later

Don’t edit k8s/ blindly — use one of these flows:

• UI: click “Scale” / “Add domain” / “Add secret” on the app’s page. Each opens a Kustomize-patch PR.
• CLI: pfai cloud … command set.
• Manual: edit k8s/ directly in the repo, push to main. Reconciler picks it up.

All paths end in a forge PR or commit, so the audit trail is automatic.

Troubleshooting

Nothing happens after I merge.

The forge webhook may not be wired. Check kubectl logs deploy/cluster-manager -n proxifai | grep webhook. If you see “deploy-from-repo disabled”, set PROXIFAI_BASE_URL and JWT_SECRET on the cluster-manager Deployment.

Build fails with “no Dockerfile and no buildpack matched”.

Add a Dockerfile at the repo root, or commit one of: package.json, go.mod, requirements.txt, pyproject.toml, Cargo.toml, Gemfile, pom.xml, build.gradle.

TLS certificate isn’t issued.

cert-manager needs to be installed in the cluster, and DNS for *.<your-apex> needs to point at the ingress controller.

The bot says “branch already exists”.

The deploy-PR branch follows the convention proxifai/deploy-setup-<random>. If a stale one is around, delete it from the forge and re-run pfai deploy.

Sample repo

A minimal Node.js sample is available at:

git clone https://github.com/proxifai/sample-hello-world
cd sample-hello-world
pfai deploy

The repo is intentionally tiny: a single server.js returning “hello, world” + a package.json. The buildpack auto-detects the Node runtime, so no Dockerfile is needed.