Skip to main content

Deployment & environments

Branches​

main contains application changes. main-deploy retains repository-specific deployment files and production defaults. Merge changes into that branch rather than overwriting it with a reset.

The frontend and backend use this shared GitLab include:

include:
- project: '313/devops/313-ci-template'
file: '/docker/gcp-dockerfile-template.yml'

The template builds a Dockerfile, pushes the image to Artifact Registry, and deploys the configured Cloud Run service. Its branch rules target main-deploy.

Shared GitLab variables​

VariablePurpose
GCP_SERVICE_KEY_B64CI service-account credential supplied through GitLab
GCP_PROJECT_IDProject containing the registry and Cloud Run service
GCP_REGIONDeployment region
GCP_REPOSITORYArtifact Registry repository
CLOUD_RUN_SERVICEThe service for this particular repository

CLOUD_RUN_SERVICE must identify the correct app. Set a separate project value such as tuition-docs for this repository.

Application URLs and secrets​

Angular uses filerUrl; Spring uses microservices.filer.url. Both environments currently point to https://print.tigasatutiga.com.

The shared delivery token is configured as PRINT_WORKER_TOKEN. Supply matching runtime values to Spring and Laravel. Keep Google, SMTP, FTP, Telegram, and database credentials in the relevant host's secret/environment configuration, never this documentation repository.

CORS allows an origin to make browser requests; it is not a replacement for access control.

Backend migrations​

Flyway runs on backend startup. The current additions are V3 (outbox, parent/month uniqueness, nullable subject on invoice items) and V4 (invoice payments).

The legacy subject foreign key uses INT(14) on both sides. V3 preserves that type when changing nullability. Changing it to BIGINT causes a foreign-key error. V3 is safe to resume when its index already exists after a partial failure.

Repair only a reviewed failure. Never use broad repair or history deletion to conceal unrelated checksum mismatches.

cPanel print layout​

The public document root contains the entry point, rewrite rules, and public files. The Laravel application lives outside public_html:

/home/CPANEL_USER/
├── .apps/tuition-print/
│ ├── releases/
│ ├── current -> releases/ACTIVE-RELEASE
│ └── shared/
│ ├── .env
│ ├── auth/
│ ├── storage/
│ └── database.sqlite
└── public_html/printing-service/
├── index.php
└── .htaccess

current selects a release. Shared credentials, storage, and delivery data survive deployments. The public index.php loads the private Laravel runtime.

Both CLI and web PHP need the required extensions. The host's Alt-PHP 8.3 setup uses an account-specific extension configuration; a working CLI alone does not prove web PDF generation works.

The GitLab print pipeline uses the cpanel runner tag and inherited SSH variables. First provisioning uses protected file variables PRINT_ENV_FILE and PRINT_GOOGLE_CREDENTIALS_FILE. Cron invokes artisan schedule:run each minute with the same PHP extension configuration.

Tuition Docs container​

This repo can reuse the shared Docker CI template because that template is framework-independent. Its Dockerfile is specific to Docusaurus:

  1. Node 22 runs npm ci and npm run build.
  2. Docusaurus writes pre-rendered static pages to build/.
  3. Nginx serves those files on port 8080 and exposes /healthz.

The Angular Dockerfile copies dist/tuition-frontend/browser; it must not be copied unchanged. Docusaurus also needs real 404 responses rather than an Angular-style fallback to the homepage for unknown URLs.

DOCS_URL is the canonical public documentation origin. The tuition-docs GitLab project supplies DOCS_URL as a Docker build argument. The initial Cloud Run origin is https://tuition-docs-421927856826.asia-southeast1.run.app. A custom documentation hostname is a separate mapping; update DOCS_URL and rebuild when it changes. The repository is private; the shared template serves the deployed documentation publicly.