45559c0e-d9d4-4741-94b7-ca25b55059d3

Forgeon Projects Overview

What a Forgeon Project is, how services run, and the ways to create and scale them.

Forgeon Projects Overview

A Forgeon Project is the home for your running application: source → builds → deployments → services → domains → observability. Think of it as the unit you create, configure, and scale in Forgeon. One project can host a single service or multiple coordinated services (web, workers, cron) plus attached databases.

fast path

What a Project can be

From an operator perspective, a Project is a set of services (and optional volumes/databases) that belongs to one organization, observed and controlled together.

From a developer perspective, a Project might be:

  • a full-stack web app with a background worker
  • an API and a separate Next.js frontend
  • a database or vector index you manage under Forgeon
  • N independent services doing jobs on a schedule or queue
  • a GPU-backed service for inference or training

Projects in the same organization can talk over a private network, so you can split systems into smaller, focused services while keeping traffic off the public Internet.

Core components of a Project

  • Source & Detection — we inspect your repo for framework/runtime hints (Next.js, Django, Go, etc.) or a Dockerfile.
  • Builds & Artifacts — reproducible builds with caching; artifacts feed deployments.
  • Environments — Production, Staging, or custom. Each has its own config, secrets, and resources.
  • Services — long-running processes (web/worker/cron) with autoscaling and health checks.
  • Domains & SSL — preview URLs by default, custom domains with automatic certificates.
  • Secrets & Config — encrypted env vars, mounts, and runtime knobs per environment.
  • Databases — provision via mdx-service (Postgres, Redis, ClickHouse, …) and wire URLs automatically.
  • Observability — logs, metrics, traces (where supported), with alerting hooks.
  • Backups & Restore — scheduled snapshots and PITR (where enabled).

You can start with a single web service and add workers or cron later. Each service has its own scaling rules and health checks.

Ways to create a Project

  • Dashboard → New Project → Import from GitHub
  • Pick the repository (personal or org), confirm detection, and deploy.
  • We create default services (e.g., web) based on your framework.

2) From a Dockerfile

  • Same flow, but detection yields a Docker service using your image.
  • Great when your stack is exotic or you need full control.

3) Empty Project (advanced)

  • Dashboard → New Project → Empty
  • Add services manually by pointing to an existing image registry and setting commands/ports.
  • Use this for “orchestration-only” cases or when deploying prebuilt images.

Whatever path you choose, your app must bind 0.0.0.0 and listen on the PORT environment variable.

Services inside a Project

A Service is a runnable unit within your Project. Common types:

  • Web — receives HTTP traffic, has domains and SSL.
  • Worker — background jobs, queues, event processors.
  • Cron — scheduled tasks with retry semantics.

Each service defines:

  • Image / Start command
  • Health checks (readiness endpoint like /readyz)
  • Scaling (min/max instances, CPU/RAM/GPU as needed)
  • Networking (internal only or public, private service discovery)
good defaults
# add a lightweight readiness probe
$/readyz→ 200 when app is ready

Environments & configuration

  • Production and Staging are common; create more if needed.
  • Secrets, env vars, and scaling policies are scoped per environment.
  • Promote builds from Staging to Production, or deploy independently.

Networking & domains

  • Every deployment gets a Preview URL with SSL for quick sharing.
  • Add custom domains; we provision/renew certificates automatically.
  • Use private DNS for cross-Project calls within your organization.

Databases with mdx-service

  • Create Postgres, MySQL/MariaDB, Redis/Valkey, ClickHouse, Cassandra, QuestDB, Qdrant, OpenSearch, Trino, Dremio, FerretDB, and more.
  • Start with dev defaults; switch to managed secrets and persistent storage for prod.
  • Metrics, backups, and restore live on each database’s page.
wire database URL
# Project → Settings → Environment
$DATABASE_URL=postgres://app:***@db:5432/app

Observability & safety

  • Logs — build and runtime streams with filters.
  • Metrics — CPU/mem/disk/net, engine-specific DB metrics, latency percentiles.
  • Alerts — choose built-in recipes or wire to your pager.
  • Rollbacks — one click to revert to the last healthy deployment.

Typical workflows

  • Single-service app — import repo → detect → web service → custom domain.
  • Multi-service app — define web + worker (queues) + cron (schedules).
  • Data heavy — add ClickHouse or Postgres, enable backups, set alert thresholds.
  • AI/ML — provision a GPU service for inference, keep web on CPU.

FAQs

Can multiple Projects work together?
Yes. Use private networking to keep service-to-service traffic internal.

Can I deploy without GitHub?
Yes. Push an image to a registry and create an Empty Project with a service that references it.

How do I scale?
Per service: set min/max instances and resources; enable autoscaling on load metrics.

What about staging?
Create a Staging environment in the same Project, or a sibling Project, and wire separate databases.

next steps