🧰 System Requirements

Make sure the following are installed on your machine:

Tool	Minimum Version	Install Guide
Ubuntu	22.04 LTS	✅ You’re good
Docker	20+	https://docs.docker.com/engine/install/ubuntu/
Docker Compose	v2+	https://docs.docker.com/compose/install/
Make	4.3+	sudo apt install make
PHP	8.2+	Optional (for artisan commands locally)
Node.js	18+	Install via https://github.com/nvm-sh/nvm
NPM	9+	Comes with Node.js

---

📦 Clone the Project

Make sure to clone both frontend and backend repositories into the same parent directory:

git clone https://gitlab.com/shukry-datakraf/myinfra-backend.git
git clone https://gitlab.com/shukry-datakraf/myinfra-frontend.git

cd myinfra-backend

⚙️ Initial Setup

1. Copy .env files

cp .env.example .env

2. Run full setup (first time only)

make reset

To start containers again later:

make up

To stop containers without removing:

make stop

---

🧪 Common Makefile Commands

Make sure you're inside the project root folder.

Command	Description
make up	Start all containers
make stop	Stop containers without removing
make down	Stop and remove all containers
make restart	Rebuild and start containers
make reset	Full reset with volume + rebuild
make bash	Shell into Laravel backend container
make frontend	Shell into Nuxt frontend container
make artisan	Run artisan commands (use with cmd=...)
make npm	Run npm commands in Laravel (use cmd=...)
make logs	Tail all container logs
make frontend-log	Tail Nuxt frontend logs
make backend-log	Tail Laravel backend logs

---

💄 Migrate the Database

1. Enter Laravel container

make bash

2. Run migrations (example):

make artisan cmd="migrate"

To refresh + seed:

make artisan cmd="migrate:fresh --seed"

---

🪪 Running the App

• Laravel API: http://localhost:8000/api
• Nuxt Frontend: http://localhost:3000

---

🤩 CORS & Sanctum Setup (for Laravel + Nuxt)

Make sure in .env:

SESSION_DOMAIN=localhost
SANCTUM_STATEFUL_DOMAINS=localhost:3000

And in config/cors.php:

'paths' => ['api/*', 'sanctum/csrf-cookie'],
'supports_credentials' => true,

---

🪩 Troubleshooting

⚠️ Keycloak Client Secret Issue

If you see warnings about The "kLpQ" variable is not set or get unauthorized_client errors:

The Keycloak client secret contains a $ character that needs proper escaping:

# WRONG - Single $ is interpreted as variable
KEYCLOAK_CLIENT_SECRET=Z#v7M&2rTx9$kLpQ

# CORRECT - Use $$ to escape the $ character in .env files
KEYCLOAK_CLIENT_SECRET=Z#v7M&2rTx9$$kLpQ

Note: The $$ in .env will be interpreted as a single $ when passed to containers.

After updating .env, restart containers:

make restart

If you still get unauthorized_client errors, the Keycloak client may need to be configured for service accounts:

1. Access Keycloak Admin: http://localhost:8080 (admin/admin)
2. Go to MyInfra realm → Clients → laravel-api
3. Enable "Service accounts roles" under Settings
4. Save the client configuration

Or run the testing seeder without Keycloak by modifying the seeder to skip Keycloak user creation.

❌ Nuxt: Permission denied

Fix in Dockerfile:

RUN chmod +x node_modules/.bin/nuxt

Or in docker-compose.yml:

command: ["sh", "-c", "chmod +x node_modules/.bin/nuxt && npm run dev"]

---

🧪 Run Laravel Tests

make bash
php artisan test

OPA MODULE

Create database myinfra_opa

docker compose exec pgsql bash
psql -U postgres
CREATE DATABASE myinfra_opa;

Run Fresh Migration

make bash
php artisan migrate:fresh --database=myinfradb-opa --path=database/migrations/opa

Make Migration

make bash
php artisan make:migration --path=database/migrations/opa ..

Run Migration

make bash
php artisan migrate --database=myinfradb-opa --path=database/migrations/opa

Run Seeder

make bash
php artisan db:seed --class=Database\\Seeders\\Opa\\DatabaseSeeder --database=myinfradb-opa

API Endpoints

All endpoints require authentication.

Variable	Used By	Format (no /api)
STAGING_PGSN_API_URL	PPA, OPA, PPUN	http://myinfra-pgsn.url
STAGING_PPA_API_URL	OPA, PPUN	http://myinfra-ppa.url
BACKEND_PGSN_API_URL	Frontend (SSR)	http://myinfra-pgsn.url
BACKEND_PPA_API_URL	Frontend (SSR)	http://myinfra-ppa.url
BACKEND_OPA_API_URL	Frontend (SSR)	http://myinfra-opa.url
BACKEND_PPUN_API_URL	Frontend (SSR)	http://myinfra-ppun.url

... ...