# F-SNICAP · Developer & LLM Repository Setup Guide

This document provides complete, actionable instructions for developers and AI coding agents (LLMs) to configure, build, and release an application repository on the **F-SNICAP** platform.

---

## 1. Core Architecture & Delivery Flow

```text
[App Repo: MR -> main] -> [GitLab CI: Test & OCI Build] -> [Kargo: Digest Promotion] -> [GitOps Repo: MR & Validation] -> [Argo CD: PreSync & Rollout]
```

- **App Repository**: Contains source code, tests, `Dockerfile`, and `.gitlab-ci.yml`.
- **Non-Sensitive Config**: Stored in GitOps repositories (`gitops-noprod` for `dev`/`test`/`stage`, `gitops-prod` for `prod`) under `environments/<env>/<app>/`.
- **Application Secrets**: Stored in **OpenBao** (noprod instance for `dev`/`test`/`stage`; prod instance for `prod`) and synced into Kubernetes `Secret` objects via **External Secrets Operator (ESO)**.
- **Promotion Chain**: `dev` → `test` → `stage` → `prod` (driven by Kargo promoting the immutable OCI image digest built from `main`).

---

## 2. Git & Branching Rules

1. **Single Permanent Branch**: `main` is the only permanent branch and the sole source for release builds.
2. **Feature Workflow**:
   - Branch off `main` using a short-lived branch (`feat/...`, `fix/...`, `chore/...`).
   - Run tests and static analysis locally.
   - Open a Merge Request (MR) targeting `main`.
3. **MR Description Checklist**:
   - Summary of changes.
   - Tests executed.
   - Required database migrations (and backward compatibility notes with the currently running release).
   - New configuration keys (GitOps values) or secret keys (OpenBao) required before rollout.

---

## 3. Repository Setup Checklist (For LLMs & Developers)

When initializing or auditing an F-SNICAP application repository, ensure the following requirements are met:

### 3.1 Containerization (`Dockerfile`)
- Build an immutable, production-ready OCI image.
- Run as a non-root user (`USER nonroot` or UID `>= 1000`).
- Expose a configurable port via environment variable (e.g., `PORT`) and provide a lightweight healthcheck endpoint (`/healthz` or `/readyz`) for Kubernetes probes and Argo CD health assessment.
- **Never** bake environment-specific secrets or private credentials into the image or frontend bundle.

### 3.2 Environment Variables & Configuration Contract
Split all configuration strictly into two categories:

| Category | Storage Location | Examples | Rule |
| :--- | :--- | :--- | :--- |
| **Non-Sensitive Config** | GitOps (`environments/<env>/<app>/`) | Public URLs, feature flags, timeouts, log levels | Treat anything reaching the browser (including build-time `VITE_*` / `NEXT_PUBLIC_*` vars) as public. |
| **Application Secrets** | OpenBao (`noprod` / `prod`) → ESO → K8s Secret | DB passwords, API keys, signing tokens | Never commit values to Git, tickets, or chat. Reference only by secret key name. If a frontend call needs a private key, proxy it through the backend. |

Document all required environment variables in the project's `README.md` or `.env.example` (with dummy/empty values for secrets) so DevOps and ESO mappings stay in sync.

### 3.3 CI Pipeline (`.gitlab-ci.yml`)
- **On Merge Requests**: Run linting, typechecks, and unit/integration tests.
- **On `main`**: Build and push the container image to the registry, publishing the immutable OCI digest that Kargo will discover and promote across `dev → test → stage → prod`.
- Reference pipeline: `https://gitlab.mgmt.innovaway.it/fsnicap/applications/test-app/-/blob/67a8f22/.gitlab-ci.yml`

---

## 4. Secret Management (OpenBao + ESO)

1. Developers manage application secret values using personal accounts in **OpenBao** under the path assigned to the application:
   - `dev`, `test`, `stage` → OpenBao **noprod**
   - `prod` → OpenBao **prod**
2. When adding a new secret key:
   - Declare the key name and whether it is mandatory.
   - Populate the secret value in OpenBao for the target environments **before** requesting promotion.
   - If the OpenBao path or ESO `ExternalSecret` mapping does not exist yet, ask DevOps to provision it.
3. Reference docs:
   - OpenBao Accounts: `https://gitlab.mgmt.innovaway.it/fsnicap/platform/infrastructure/-/blob/a0bc19d/docs/openbao-accounts.md`
   - Access Policies: `https://gitlab.mgmt.innovaway.it/fsnicap/platform/infrastructure/-/blob/a0bc19d/terraform/vault-instance/modules/instance/4-policies.tf`

---

## 5. DevOps Handoff & Promotion Protocol

When requesting a promotion or preparing a release handoff to DevOps, provide this structured summary:

```markdown
### Release Handoff Request
- **Application**: <app-name>
- **Target Environment**: <dev | test | stage | prod>
- **Version / Digest**: <App MR link, commit SHA, or OCI image digest>
- **GitOps Prerequisites**: <Link to MR in gitops-noprod or gitops-prod, or "None">
- **OpenBao Prerequisites**: <List of new/updated secret key names (NO VALUES), or "None">
- **Migrations & Compatibility**: <Execution order and backward compatibility with previous release>
- **Smoke Test**: <Exact verification steps and expected result post-rollout>
```

### Troubleshooting Blocked Promotions or Regressions
1. **Blocked Promotion MR**: Inspect the `promotion-validation` CI job output in the GitOps MR and fix missing values or OpenBao secret keys.
2. **Post-Deploy Regression**: Inspect application logs and run the smoke test. Before requesting a rollback, verify compatibility with any database migrations already executed (`PreSync`).

---

## 6. Application Delivery Paths Reference

- **`test-app`**: `dev → test → stage → prod` via Kargo, with GitOps MR validation and Argo CD `PreSync` checks.
- **`DocOps`**: IaC declares the `dev` Stage and generates runtime values (`dev → prod` planned path).
- **`Nextcloud` & `OpenProject`**: Reviewed MR in `gitops-prod` and operator-triggered Argo CD sync.
- **`Keycloak`**: Non-secret config in GitOps (`dev` and `prod`); Helmfile manages installation and Terraform manages identity configuration.
