Installation, build and deployment

The steps are the same for orbix-aspnet/ (full template) and orbix-aspnet-starterkit/ (starter kit). Both are a .NET solution (Orbix.slnx) with the web app in src/Orbix and the tests in tests/Orbix.Tests.

1. Copy the project

Extract the ZIP and copy orbix-aspnet/ to your projects folder (rename it as you like). Open a terminal in that folder, or open Orbix.slnx in Visual Studio or Rider.

2. Run it

dotnet run --project src/Orbix

Open http://localhost:5000. The prebuilt assets in src/Orbix/wwwroot/build/bootstrap are used, so the template is ready without Node.js. In Visual Studio or Rider, run the http launch profile of the Orbix project.

3. Install the front-end tooling (to customize CSS and JavaScript)

cd src/Orbix
npm ci
npm run build        # production assets in wwwroot/build/bootstrap

For day-to-day work, rebuild the assets on every change next to the .NET watcher:

dotnet watch --project src/Orbix     # terminal 1 (solution folder): reloads on C# and Razor changes
npm run dev                          # terminal 2 (src/Orbix): rebuilds wwwroot/build/bootstrap on every change

4. Run the tests (optional)

dotnet test          # from the solution folder

The suite renders every page through WebApplicationFactory (no browser needed). The build tests read wwwroot/build/bootstrap, so run npm run build first after changing the assets.

Settings

src/Orbix/appsettings.json, section Orbix:

Every key can be set with an environment variable using a double underscore: Orbix__PathBase=/admin, Orbix__DefaultLocale=es.

Publish

dotnet publish src/Orbix -c Release -o ./publish

publish/ contains Orbix.dll, the Razor views compiled into it, wwwroot/ (with the built assets and the demo images), appsettings.json, menu.json and the inline assets the pages need (ClientApp/svg/sprite.svg, ClientApp/js/boot/*.js). Run it with:

dotnet publish/Orbix.dll --urls http://0.0.0.0:5000

Set ASPNETCORE_ENVIRONMENT=Production on servers (the default when it is not set): errors then show the Orbix 500 page instead of the developer exception page.

Deploy with Kestrel only

Kestrel is a production web server. Run the published app as a service (systemd on Linux, a Windows service or your container platform) and give it HTTPS, either with a certificate in Kestrel's configuration (Kestrel:Endpoints in appsettings.json) or, more commonly, behind a reverse proxy (Nginx, IIS, a load balancer) that terminates TLS.

Deploy on IIS (Windows Server)

1. Install the ASP.NET Core 10 Hosting Bundle on the server and restart IIS (iisreset).
2. Publish (dotnet publish src/Orbix -c Release -o C:\inetpub\orbix). The publish step writes the web.config for the ASP.NET Core Module.
3. In IIS Manager create an application pool with .NET CLR version: No Managed Code, then a site (or an application under an existing site) whose physical path is C:\inetpub\orbix, using that pool.
4. Give the pool identity read access to the folder.

As an IIS application under a site (for example https://intranet.example.com/admin), IIS passes the sub-path to the app automatically: leave Orbix:PathBase empty.

Deploy on Linux behind Nginx

1. Install the ASP.NET Core 10 runtime, publish and copy publish/ to /var/www/orbix.

2. Create the service /etc/systemd/system/orbix.service:

   [Unit]
   Description=Orbix admin
   After=network.target
   
   [Service]
   WorkingDirectory=/var/www/orbix
   ExecStart=/usr/bin/dotnet /var/www/orbix/Orbix.dll --urls http://127.0.0.1:5000
   Restart=always
   RestartSec=10
   User=www-data
   Environment=ASPNETCORE_ENVIRONMENT=Production
   Environment=ASPNETCORE_FORWARDEDHEADERS_ENABLED=true
   
   [Install]
   WantedBy=multi-user.target

   Then sudo systemctl enable --now orbix.

3. Proxy it from Nginx (add TLS with your certificate or Certbot):

   server {
       listen 80;
       server_name admin.example.com;
   
       location / {
           proxy_pass         http://127.0.0.1:5000;
           proxy_http_version 1.1;
           proxy_set_header   Host $host;
           proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header   X-Forwarded-Proto $scheme;
       }
   }

ASPNETCORE_FORWARDEDHEADERS_ENABLED=true makes the app trust the X-Forwarded-* headers, so it sees the real scheme (https) and client address.

Serve the app under a sub-path (path base)

To publish the template at https://example.com/admin/ behind a reverse proxy, set the path base:

"Orbix": { "PathBase": "/admin" }

and keep the prefix when proxying (no trailing slash after the address in proxy_pass):

location /admin/ {
    proxy_pass       http://127.0.0.1:5000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Every link (Url.Page()), asset, image, the language endpoint and the culture cookie follow the path base. The built assets use relative URLs, so the same wwwroot/build/bootstrap works at any path.

Docker

A two-stage image, from the solution folder (add a .dockerignore with **/bin, **/obj and **/node_modules):

# Build and publish
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish src/Orbix -c Release -o /app

# Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
USER app
ENTRYPOINT ["dotnet", "Orbix.dll"]

docker build -t orbix .
docker run -p 8080:8080 orbix

The image uses the prebuilt assets of src/Orbix/wwwroot/build. To rebuild them inside Docker, add a first stage FROM node:24 AS assets that runs npm ci && npm run build in src/Orbix and copy its wwwroot/build into the build stage before dotnet publish.

Troubleshooting