Skip to content

New Project Setup

The end-to-end guide for bootstrapping a brand-new App-name application on the Twycis shared setup — from an empty GitHub repo to a deployed, tagged, go-live-ready stack. Work through the phases in order; each one links the deep-dive page for the details.

Joining an existing project instead?

If the repo already exists and you just need a working local environment, use Developer Onboarding.

Two environments only

Every Twycis project runs test and production — nothing in between. Provision both from the start so the pipeline has somewhere to deploy on day one.

Overview

flowchart TD
    A[1. Repo + skills] --> B[2. Infrastructure]
    B --> C[3. Supabase test + prod + local]
    C --> D[4. Secrets + GitHub environments]
    D --> E[5. SonarCloud]
    E --> F[6. Deploy workflows + first deploy]
    F --> G[7. First release tag]
    G --> H[Go-live checklist]

Phase 1 — Create the repo and vendor the skills

  1. Create the repository under the Twycis org: github.com/<org>/app-name.
  2. Scaffold the monorepo layout — ./frontend (React + Vite + TS, Node 24) and ./backend (Node/Express or FastAPI).
  3. Vendor the canonical skills into the repo. These are the shared slash-command workflows and the architecture-enforcement gate that every Twycis project carries. The CI skills-check verifies they are present and unmodified.
gh repo create <org>/app-name --private --clone
cd app-name
# vendor the canonical skills directory into the repo

The skills gate is mandatory

The pipeline will fail if the canonical skills are missing or drift from their source of truth. Set them up now so later phases stay green. See Skills Check and Agent Workflows.

Phase 2 — Provision infrastructure

Stand up one host per environment (app-name test and app-name-prod), each fronted by Cloudflare Tunnel and nginx. There are no exposed ports — all ingress flows through the tunnel.

Step What you provision Deep dive
2a EC2 instance per environment, Docker installed, deploy paths /opt/app-name and /opt/app-name-prod AWS EC2
2b Cloudflare Tunnel for CI/CD deploys and admin SSH (WARP/Zero Trust) Cloudflare Tunnel
2c nginx reverse proxy + TLS in front of the app containers nginx

Map the DNS records while you are here: test.<your-domain> → test host, <your-domain> → production host.

Phase 3 — Supabase (test, prod, and local)

  1. Create two Supabase projects — one for test, one for production — and capture each project's URL, anon key, and service-role key. See Supabase (Online).
  2. Configure Auth on both: Google and Microsoft OAuth providers, and TOTP MFA. (The login → JWT → backend-verify flow is documented in Auth Flow.)
  3. Set up local Supabase for development so engineers never touch the cloud projects to build features. See Supabase (Local).
  4. Apply the initial schema with Alembic (cd backend && alembic upgrade head) — see Migrations.

Keep the service-role key server-side

The service-role key is injected into the backend only. It must never reach the frontend or appear in any VITE_-prefixed variable.

Phase 4 — Secrets and GitHub environments

Create the two GitHub Environments — test and production — and populate their secrets. Production should require manual approval before a deploy can run.

  • Configure repository and environment secrets (Supabase keys, DATABASE_URL, deploy credentials, image registry auth). See Secrets & Environment.
  • Cross-check every required key against the canonical Secrets Matrix so nothing is missing per environment.

Container images publish to GHCR as ghcr.io/<org>/app-name-backend and ghcr.io/<org>/app-name-frontend.

Phase 5 — SonarCloud

Wire the repo to SonarCloud so quality and coverage gates run on every push and PR. See SonarCloud. Add the SONAR_TOKEN to repository secrets and confirm the analysis step appears in the pipeline.

Phase 6 — Deploy workflows and first deploy

Add the GitHub Actions workflows that build, push to GHCR, and deploy over the Cloudflare Tunnel. The full pipeline shape — build → scan → push → deploy — is described in Pipeline Overview.

  1. Add the build/test/scan workflow (runs the architecture check, tests, and SonarCloud).
  2. Add the deploy workflow: push to main → deploy to test automatically; tag vX.Y.Z → deploy to production with approval.
  3. Trigger the first deploy by pushing to main and confirm test.<your-domain> serves the app.
git add .
git commit -m "chore: initial app-name scaffold + CI/CD"
git push origin main   # triggers the automatic test deploy

Phase 7 — Cut the first release tag

Once test is verified, ship production by tagging the first release. The version lives in frontend/package.json; the tag push is what triggers the production deploy.

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

The full semantic-versioning scheme, version display, build-time injection, and rollback procedure are in Version Control. The production deploy mechanics are in Deploy to Production.

Go-live checklist

  • [ ] Repo created under <org> with the canonical skills vendored and the skills-check passing.
  • [ ] EC2 test and production hosts provisioned; Docker installed; deploy paths in place.
  • [ ] Cloudflare Tunnel live for both environments; no public ports open; WARP/Zero Trust SSH working.
  • [ ] nginx + TLS serving test.<your-domain> and <your-domain>.
  • [ ] DNS records pointing at the correct hosts.
  • [ ] Supabase test + production projects created; OAuth (Google + Microsoft) and TOTP MFA configured.
  • [ ] Local Supabase documented and working for the team.
  • [ ] Initial schema migrated via Alembic on both environments.
  • [ ] GitHub test and production environments created; production gated by manual approval.
  • [ ] All secrets set and reconciled against the Secrets Matrix.
  • [ ] SonarCloud connected; quality gate green.
  • [ ] Test deploy verified end-to-end on push to main.
  • [ ] v1.0.0 tagged; production deploy verified; version + environment shown correctly in the app.
  • [ ] Developer Onboarding updated with any project-specific notes for the next engineer.