Installation

The steps are the same for orbix-angular/ (full template) and orbix-angular-starterkit/ (starter kit).

1. Copy the project

Extract the ZIP and copy orbix-angular/ to your projects folder (rename it as you like). Open a terminal in that folder.

2. Install the dependencies

npm install

The design system is installed from the local folder packages/foundry-ui/ (no registry account needed). npm ci installs the exact versions of package-lock.json (recommended in CI and Docker).

3. Run the dev server

npm start

Open http://localhost:4200. Edits to components, templates, styles and translations reload the page instantly.

4. Build for production

npm run build

dist/tailwind/ now holds the whole app: index.html, the hashed CSS and JavaScript files (one chunk per page and per language), the font files and their licenses in media/, the demo photos in images/, the icon sets in icon-sets/, favicon.svg and 3rdpartylicenses.txt (license texts of the bundled packages, written by the Angular CLI). Check it locally with npm run preview.

5. Run the tests (optional)

npm run build        # the build suite checks the production output
npm test

The tests run in Node.js on a simulated DOM (happy-dom): no browser is installed or opened.

Deploy

Upload the contents of dist/tailwind/ to your host. The app uses clean URLs (/apps/kanban, the Angular Router with the path location strategy), so the server must answer every path that is not a file with index.html (the SPA fallback); otherwise a reload on any page other than the home page returns 404.

Netlify

Create public/_redirects (it is copied into the build) with:

/*  /index.html  200

Build command npm run build, publish directory dist/tailwind.

Vercel

Framework preset "Other", build command npm run build, output directory dist/tailwind, and a vercel.json file in the project root:

{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

GitHub Pages, Cloudflare Pages and other static hosts

Publish dist/tailwind and enable the host's single-page app setting (Cloudflare Pages does it by default when there is no 404.html). On GitHub Pages, copy index.html to 404.html after the build so that deep links load the app, and build with the repository name as base path (see Sub-folder).

Nginx

server {
  listen 80;
  server_name admin.example.com;
  root /var/www/orbix;            # contents of dist/tailwind
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  # Hashed file names: cache them for a year (index.html is never cached this way).
  location ~* \.(?:js|css|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

Apache

In the virtual host or an .htaccess file next to index.html:

FallbackResource /index.html

IIS, S3 + CloudFront and others

Configure a rewrite (IIS URL Rewrite) or a custom error response (CloudFront: 403 and 404 → /index.html, status 200) that serves index.html for unknown paths.

Sub-folder

To serve the app from a sub-folder (for example https://example.com/admin/), build with the base path and point the fallback to that folder:

ORBIX_BASE=/admin/ npm run build          # Windows PowerShell: $env:ORBIX_BASE="/admin/"; npm run build

scripts/assets.mjs writes the base path into index.html (<meta name="orbix-base">, read by src/core/paths.ts) and scripts/build.mjs passes it to the Angular CLI as --deploy-url, so the script and stylesheet URLs, the router (APP_BASE_HREF), every routerLink, image and asset URL follow it. The app sets no <base href> element on purpose: the inline SVG icon sprite (<use href="#icon">) keeps working in every browser. Nginx: location /admin/ { try_files $uri $uri/ /admin/index.html; }. Apache: FallbackResource /admin/index.html.

Docker

A two-stage image: build with Node.js, serve with Nginx. Save as Dockerfile in the project folder:

# Build
FROM node:24-alpine AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build

# Serve
FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist/tailwind /usr/share/nginx/html
EXPOSE 80

and nginx.conf next to it:

server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;
  location / { try_files $uri $uri/ /index.html; }
  location ~* \.(?:js|css|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; }
}

Then docker build -t orbix-admin . and docker run -p 8080:80 orbix-admin (open http://localhost:8080). Add a .dockerignore with node_modules, dist and .angular to keep the build context small. For a sub-folder, use RUN npm ci && ORBIX_BASE=/admin/ npm run build and copy the files into /usr/share/nginx/html/admin.

Troubleshooting