45559c0e-d9d4-4741-94b7-ca25b55059d3
Forgeon Docs

Documentation, guides, and patterns to help you build on Forgeon — from your first deploy to running serious infrastructure.

Install Forgeon

What you need before your first deploy: account, repo access, and app runtime expectations.

Last updated: 2026-03-17

This page covers the minimum prerequisites to deploy successfully. If you complete this checklist, the rest of the Forgeon flow is smooth.

Prerequisites

  • A GitHub account with repo access (personal or org)
  • A Forgeon account (free tier is fine)
  • A web app that binds to 0.0.0.0 and uses PORT

App requirements (must‑haves)

Forgeon expects your app to:

  1. Start with a command (e.g. npm start)
  2. Bind to 0.0.0.0
  3. Listen on PORT (do not hardcode a port)

If any of these are missing, the deploy will build but the runtime won’t be reachable.

GitHub App install

Forgeon connects to GitHub through a GitHub App for secure repo access.

  1. Go to Settings → Git in the dashboard.
  2. Click Install GitHub App.
  3. Choose All repos or Only selected repos.

You can change the selection later from GitHub → Settings → Applications.

Recommended repo structure

Forgeon detects common frameworks by inspecting:

  • package.json and lockfiles (Node)
  • requirements.txt or pyproject.toml (Python)
  • go.mod (Go)
  • Dockerfile (Docker)

If a repo is unusual, you can override detection in Build & Deployment.

Troubleshooting

App builds but shows 502/blank page

  • Ensure your app binds to 0.0.0.0 and uses the PORT env

Repo not visible

  • Check GitHub App permissions for the repo or org

Build works locally but fails on Forgeon

  • Verify you committed lockfiles and build scripts

Next