Developer

Thulija Workspace – Developer Onboarding Guide

Introduction

Welcome to Thulija Workspace.

This guide explains how developers should:

clone the workspace

initialize project repositories

start the Docker environment

use VS Code Dev Containers

run enterprise applications

commit project changes correctly

This guide is intended for developers who are joining an existing Thulija Workspace environment.

Final Workspace Structure

thulijaworkspace/
|
+-- Dockerfile.allinone
+-- docker-compose.yml
+-- start.sh
+-- index.js
+-- package.json
+-- .devcontainer/
|   +-- devcontainer.json
|
+-- workspaces/
    +-- tcoach/        <- submodule
    |   +-- input/
    |   +-- output/
    |   +-- projects/
    |
    +-- clinic/        <- submodule
        +-- input/
        +-- output/
        +-- projects/

Step 1 – Install Required Software

Install the following software:

Required

Docker Desktop

Visual Studio Code

Git

VS Code Extensions

Install:

Dev Containers

Optional But Recommended

GitHub Desktop

GitHub CLI

Step 2 – Clone Main Workspace Repository

Clone the main workspace repository.

Example:

git clone https://github.com/<username>/thulija-workspace.git

Enter the workspace folder:

cd thulija-workspace

Step 3 – Initialize Git Submodules

Run:

git submodule update --init --recursive

This downloads all project repositories attached to the workspace.

Example:

workspaces/
+-- tcoach/
    +-- input/
    +-- output/
    +-- projects/

Important:

You must have GitHub access to the private repositories.

If submodule initialization fails:

verify GitHub access

verify repository permissions

verify GitHub authentication

Step 4 – Start Docker Environment

From the workspace root:

docker compose up --build -d

This command:

builds the development container

creates the Docker container

starts MariaDB

mounts the workspace into Docker

exposes development ports

Step 5 – Verify Docker Container

Run:

docker ps

Expected container:

thulija_app

Step 6 – Open Workspace in VS Code

Open:

thulija-workspace

Then press:

Ctrl + Shift + P

Run:

Dev Containers: Reopen in Container

VS Code will reopen inside the Docker container.

Step 7 – Verify Development Environment

Inside the VS Code terminal run:

pwd

Expected:

/workspace

Verify tools:

node -v
php -v
composer --version
ng version
ionic --version

If all commands work, the development environment is ready.

Step 8 – Project Workspace Structure

Each enterprise application follows this structure:

workspaces/tcoach/
|
+-- input/
+-- output/
+-- projects/

Purpose:

input/     -> metadata definitions
output/    -> generated source code
projects/  -> runnable applications

Step 9 – Generate / Assemble Project

From the workspace root:

node index.js tcoach

Expected responsibilities:

read metadata

generate source code

assemble Laravel project

assemble Angular project

prepare runtime environment

Step 10 – Run Laravel Application

Example:

cd workspaces/tcoach/projects/tcoach
php artisan serve --host=0.0.0.0 --port=80

Access from browser:

http://localhost:8081

Step 11 – Run Angular Application

Open another VS Code terminal.

Example:

cd workspaces/tcoach/projects/tcoach/webclient
ng serve --host=0.0.0.0 --port=4200

Access from browser:

http://localhost:4201

Step 12 – Run Ionic Application

Open another VS Code terminal.

Example:

cd workspaces/tcoach/projects/tcoach/mobileclient
ionic serve --host=0.0.0.0 --port=8100

If required, add Ionic port mapping inside:

docker-compose.yml

Example:

ports:
– "8101:8100"

Browser URL:

http://localhost:8101

Step 13 – Commit Project Changes

Important:

Each project inside:

workspaces/tcoach

is a Git submodule.

Project changes must first be committed INSIDE the submodule.

Commit Project Repository Changes

Go to project repository:

cd workspaces/tcoach

Check status:

git status

Commit changes:

git add .
git commit -m "Update tcoach project"
git push

Update Main Workspace Reference

Return to main workspace:

cd ../..

Check status:

git status

Commit updated submodule pointer:

git add workspaces/tcoach
git commit -m "Update tcoach submodule reference"
git push

Important:

The main workspace stores only the reference to the project version.

The actual source code belongs to the project repository.

Step 14 – Pull Latest Changes

Update main workspace:

git pull

Update submodules:

git submodule update --init --recursive

If latest submodule commits are required:

git submodule update --remote --merge

Common Problems

Problem 1 – Docker Not Running

Error example:

failed to connect to docker daemon

Solution:

Open Docker Desktop first.

Then rerun:

docker compose up --build -d

Problem 2 – Dev Container Cannot Open Workspace

Verify:

.devcontainer/devcontainer.json

Content:

{
  "name": "Thulija Workspace",
  "dockerComposeFile": [
    "../docker-compose.yml"
  ],
  "service": "app",
  "workspaceFolder": "/workspace",
  "shutdownAction": "stopCompose"
}

Problem 3 – Submodule Is Empty

Run:

git submodule update --init --recursive

Problem 4 – Tools Missing Inside VS Code

You may not be inside the Dev Container.

Verify VS Code bottom-left corner.

Expected:

Dev Container: Thulija Workspace

Problem 5 – GitHub Repository Not Found

Usually caused by:

missing GitHub permissions

private repository access issues

incorrect GitHub authentication

Verify repository access using browser or GitHub Desktop.

Developer Quick Start Summary

git clone https://github.com/<username>/thulija-workspace.git
cd thulija-workspace
git submodule update --init --recursive
docker compose up --build -d

Open VS Code:

Dev Containers: Reopen in Container

Then run:

node index.js tcoach

Final Notes

This environment is designed for:

enterprise software development

metadata-driven systems

remote teams

scalable onboarding

project isolation

Dockerized development

VS Code Dev Containers

Git submodule architecture

Always keep Docker Desktop running before opening the Dev Container.