docs: deployment notes for nginx, Apache httpd and Tomcat

2026-08-15 15:33:19 +05:30
parent 053a1cee05
commit 88702f2b43
1 changed files with 232 additions and 0 deletions
@@ -0,0 +1,232 @@
+# Deploying UdyamLinc
+
+Two artifacts, one host.
+
+| Artifact | Built from | Output |
+|---|---|---|
+| API | `UdyamLinc-Backend` | `target/udyamlinc-backend.jar` (~80 MB, executable) |
+| UI | `UdyamLinc-UI` | `dist/` (static files, ~880 kB) |
+
+The UI bundle is built with `VITE_UDYAM_API_BASE_URL=/api/v1/udyam` — a **relative**
+path. It therefore contains no hostname, serves correctly from any domain, and is
+same-origin with the API. That last point is the one worth keeping: same-origin means
+CORS never applies, and CORS is the single largest source of "worked locally, broken on
+the server" in a split deployment.
+
+The only requirement on the web server is that it does two things:
+
+1. serve `dist/` with an SPA fallback — unknown paths return `index.html`, because
+   React Router owns `/officer/**`, `/nabard/**` and `/app/**`, not the file system;
+2. pass `/api/**` through to the Spring Boot process on port 8082.
+
+Any of nginx, Apache httpd or Tomcat can do both. Pick the section that matches your box.
+
+---
+
+## 1. The API (identical in all three cases)
+
+The jar embeds Tomcat 11. It does not need an application server installed, and it does
+not go in `webapps/`.
+
+```bash
+java -jar udyamlinc-backend.jar
+```
+
+Configuration is entirely by environment variable — nothing needs editing inside the jar:
+
+```bash
+export UDYAM_DB_URL=jdbc:postgresql://localhost:5432/UdyamLinc_DEMO
+export UDYAM_DB_USERNAME=postgres
+export UDYAM_DB_PASSWORD=<the real one>
+
+# Set this. The default is committed to the repository, so it is public, and a
+# signing key anyone can read signs anyone's token.
+export UDYAM_JWT_SECRET=<a long random string>
+```
+
+`spring.jpa.hibernate.ddl-auto=update` builds the schema on first boot, so the database
+only has to exist and be empty:
+
+```sql
+CREATE DATABASE "UdyamLinc_DEMO";
+```
+
+### As a systemd service
+
+```ini
+[Unit]
+Description=UdyamLinc API
+After=network.target postgresql.service
+
+[Service]
+User=udyamlinc
+WorkingDirectory=/opt/udyamlinc
+Environment=UDYAM_DB_URL=jdbc:postgresql://localhost:5432/UdyamLinc_DEMO
+Environment=UDYAM_DB_USERNAME=postgres
+Environment=UDYAM_DB_PASSWORD=change-me
+Environment=UDYAM_JWT_SECRET=change-me
+ExecStart=/usr/bin/java -jar /opt/udyamlinc/udyamlinc-backend.jar
+SuccessExitStatus=143
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### First boot takes a while, and the failure mode is silent
+
+`UdyamDataSeeder` populates 263 enterprises across 8 partner banks and 16 branches, and
+it runs as **one transaction**. Nothing is visible in the database until it commits.
+
+This has bitten us once already: the machine slept mid-seed, the transaction stayed open
+overnight, and every figure read from the console during that window was the pre-seed
+state — reported confidently, with no warning anywhere. **Watch for the seeder's final
+log line before trusting any number on screen**, and check its timestamp rather than
+just its text.
+
+Verify the API is up:
+
+```bash
+curl -s localhost:8082/api/v1/udyam/auth/regional-offices
+```
+
+That endpoint is deliberately public — the login page reads it before anyone has signed
+in — so it is a clean liveness check.
+
+---
+
+## 2a. Front door: nginx
+
+`UdyamLinc-UI/nginx.conf` is ready to use as-is. Copy `dist/` to the document root and
+the conf to `/etc/nginx/conf.d/`. It already carries the `/api/` proxy block, the SPA
+fallback, gzip, and asset caching.
+
+Adjust `listen 5173` to `80`/`443` for a real deployment.
+
+---
+
+## 2b. Front door: Apache httpd
+
+Enable the modules first — on a stock install `proxy_http` and `rewrite` are usually off:
+
+```bash
+a2enmod proxy proxy_http rewrite headers
+```
+
+Virtual host:
+
+```apache
+<VirtualHost *:80>
+    ServerName udyamlinc.lincpay.tech
+    DocumentRoot /var/www/udyamlinc
+
+    # ── API ─────────────────────────────────────────────
+    # The backend's context-path is already /api/v1/udyam, so the prefix passes
+    # through unchanged rather than being rewritten.
+    ProxyPreserveHost On
+    ProxyPass        /api/  http://127.0.0.1:8082/api/
+    ProxyPassReverse /api/  http://127.0.0.1:8082/api/
+
+    # Ingestion and the three-year backfill are long-running admin calls. The
+    # default proxy timeout cuts them off mid-run and reports a gateway error
+    # over a job that is still working.
+    ProxyTimeout 300
+
+    <Directory /var/www/udyamlinc>
+        Require all granted
+        Options -Indexes
+
+        # ── SPA fallback ────────────────────────────────
+        # Anything that is not a real file, not a real directory, and not the
+        # API is handed to index.html for React Router to resolve. Without the
+        # !^/api/ guard this rule swallows API calls and returns HTML to axios,
+        # which surfaces as a JSON parse error rather than a routing problem.
+        RewriteEngine On
+        RewriteCond %{REQUEST_URI} !^/api/
+        RewriteCond %{REQUEST_FILENAME} !-f
+        RewriteCond %{REQUEST_FILENAME} !-d
+        RewriteRule . /index.html [L]
+    </Directory>
+
+    # Fingerprinted assets are immutable; index.html must never be cached or a
+    # deploy cannot reach browsers that already have it.
+    <LocationMatch "^/assets/">
+        Header set Cache-Control "public, max-age=2592000, immutable"
+    </LocationMatch>
+    <LocationMatch "^/index\.html$">
+        Header set Cache-Control "no-cache, no-store, must-revalidate"
+    </LocationMatch>
+</VirtualHost>
+```
+
+---
+
+## 2c. Front door: Tomcat
+
+Two things are worth separating here, because "Tomcat" can mean either.
+
+### Serving the UI from Tomcat — fine
+
+Copy `dist/` into `$CATALINA_HOME/webapps/ROOT/` and add the SPA fallback via the
+rewrite valve. In `conf/Catalina/localhost/ROOT.xml` (or the `<Context>` element):
+
+```xml
+<Context>
+    <Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
+</Context>
+```
+
+with `webapps/ROOT/WEB-INF/rewrite.config`:
+
+```
+RewriteCond %{REQUEST_URI} !^/api/
+RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-f
+RewriteRule ^(.*)$ /index.html
+```
+
+The API still runs as its own `java -jar` process on 8082, and Tomcat proxies to it —
+or you put httpd/nginx in front of both.
+
+### Deploying the API *as a WAR* into Tomcat — do not do this today
+
+It is possible but it is not a same-day change, and the constraint is hard rather than
+stylistic:
+
+- This project is **Spring Boot 4.0.1**, which is built on Jakarta EE 11 / Servlet 6.1.
+  That requires **Tomcat 11**. On Tomcat 9 or 10 the application does not start —
+  Tomcat 9 is `javax.*` and cannot load a `jakarta.*` application at all.
+- It needs `<packaging>war</packaging>`, `spring-boot-starter-tomcat` moved to
+  `provided`, and `UdyamLincApplication` extending `SpringBootServletInitializer`.
+- The context path moves from the configured `/api/v1/udyam` to the WAR's deployed
+  name, so the proxy rules above stop matching.
+
+The jar already embeds Tomcat 11, so running it directly gives the same container with
+none of that risk. **Recommendation: keep the jar.**
+
+---
+
+## Checklist before showing anyone
+
+- [ ] `curl localhost:8082/api/v1/udyam/auth/regional-offices` returns JSON
+- [ ] The seeder's final log line has appeared, with a plausible timestamp
+- [ ] The site loads, and a hard refresh on a deep link such as `/nabard/geography`
+      returns the app rather than a 404 — this is the SPA fallback, and it is the
+      single most common thing to get wrong
+- [ ] The browser network tab shows `/api/v1/udyam/...` calls returning 200, not HTML
+- [ ] `UDYAM_JWT_SECRET` is not the committed default
+
+## What is deliberately off
+
+`udyam.ingestion.enabled` is `false`, so a demo boot never calls a government endpoint,
+and `DATAGOV_API_KEY` is unset. The portfolio is seeded, which is enough for every
+screen. To refresh from live sources, set the key and run, in order:
+
+```
+POST /admin/ingestion/run
+POST /admin/features/compute
+POST /admin/scoring/run
+```
+
+Space bulk ingestion runs a couple of minutes apart — data.gov.in meters by quota per
+window, so a run started too soon after another returns 429 on every pair at once and
+records the whole ingestion as failed with zero rows.