Local deploy tagging (#1134)

* added profiled services and prevented nginx loop when profiled services are inactive

* update local development guide in docs to include profile information

Author: taylerhn

apps/docs/src/getting-started/local-development.md

@@ -81,6 +81,35 @@ docker compose down
 docker compose up --build -d
 ```
 
+## Docker Compose Profiles
+
+By default, running `docker compose up -d` starts only the **core stack** (backend, frontend, MongoDB, Redis). Additional services are **opt-in** and can be enabled using Docker Compose profiles.
+
+Profiles allow you to start only the services you need for your workflow, keeping local development less resource-intensive.
+
+- `ag` — AG frontend  
+  → http://localhost:3001  
+
+- `staff` — Staff dashboard  
+  → http://localhost:3002  
+
+- `semantic-search` — Semantic course search  
+  → http://localhost:3010  
+
+- `docs` — Docs + Storybook  
+  → http://localhost:3003 / http://localhost:3005  
+
+- `dev` — MinIO (staff photo uploads)  
+  → http://localhost:3006  
+
+```sh
+# Start core + staff dashboard
+docker compose --profile staff up -d
+
+# Start multiple profiles
+docker compose --profile ag --profile staff up -d
+```
+
 ## Ports
 `docker compose up` will automatically setup certain services on your localhost ports. By default, `DEV_PORT_PREFIX` is set to `30`, which means services will be available on ports starting with `30XX`. You can adjust this by setting the `DEV_PORT_PREFIX` environment variable if you need to run multiple instances of the repository in parallel (e.g., for git worktree setups).
 

docker-compose.yml

@@ -32,6 +32,8 @@ services:
       - ./apps/backend:/backend/apps/backend
       - ./packages:/backend/packages
   semantic-search:
+    profiles:
+      - semantic-search
     build:
       context: ./apps/semantic-search
       dockerfile: Dockerfile
@@ -59,6 +61,8 @@ services:
       - ./apps/frontend:/frontend/apps/frontend
       - ./packages:/frontend/packages
   ag-frontend:
+    profiles:
+      - ag
     build:
       context: .
       dockerfile: ./apps/ag-frontend/Dockerfile
@@ -70,6 +74,8 @@ services:
       - ./apps/ag-frontend:/ag-frontend/apps/ag-frontend
       - ./packages:/ag-frontend/packages
   staff-frontend:
+    profiles:
+      - staff
     build:
       context: .
       dockerfile: ./apps/staff-frontend/Dockerfile
@@ -177,10 +183,6 @@ services:
         condition: service_healthy
       frontend:
         condition: service_started
-      ag-frontend:
-        condition: service_started
-      staff-frontend:
-        condition: service_started
     image: nginx:1.21
     networks:
       - bt
@@ -224,6 +226,8 @@ services:
         redis-cli -h redis FLUSHALL
         echo "Flushed redis cache on startup."
   storybook:
+    profiles:
+      - docs
     build:
       context: .
       dockerfile: ./apps/storybook/Dockerfile
@@ -237,6 +241,8 @@ services:
       - ./packages/theme:/storybook/packages/theme
       - ./apps/storybook:/storybook/apps/storybook
   docs:
+    profiles:
+      - docs
     build:
       context: .
       dockerfile: ./apps/docs/Dockerfile

nginx.conf

@@ -41,6 +41,9 @@ server {
     server_name  localhost;
     access_log   off;
 
+    #Docker's embedded DNS in order to resolve upstream names at request time
+    resolver 127.0.0.11 valid=5s;
+
     # Backend API
     location /api {
         proxy_set_header Host $http_host;
@@ -63,9 +66,11 @@ server {
         proxy_pass http://backend:5001;
     }
 
-    # Frontend
+    # Frontend (ag-frontend is a profiled service)
     location / {
-        proxy_pass http://ag-frontend:3001;
+        # (use a variable so DNS resolves at request time)
+        set $ag_frontend http://ag-frontend:3001;
+        proxy_pass $ag_frontend;
 
         # Ensure Nginx properly handles WebSocket requests
         proxy_http_version 1.1;
@@ -79,6 +84,9 @@ server {
     server_name  localhost;
     access_log   off;
 
+    #Docker's embedded DNS in order to resolve upstream names at request time
+    resolver 127.0.0.11 valid=5s;
+
     # Backend API
     location /api {
         proxy_set_header Host $http_host;
@@ -101,9 +109,11 @@ server {
         proxy_pass http://backend:5001;
     }
 
-    # Frontend
+    # Frontend (staff-frontend is a profiled service)
     location / {
-        proxy_pass http://staff-frontend:3002;
+        # (use a variable so DNS resolves at request time)
+        set $staff_frontend http://staff-frontend:3002;
+        proxy_pass $staff_frontend;
 
         # Ensure Nginx properly handles WebSocket requests
         proxy_http_version 1.1;