Skip to main content

Move the Trisul web interface off port 3000

FieldValue
App Note IDAN-012
AudienceTrisul admins, NOC and network engineers
Applies toAll product modes

Summary​

WebTrisul listens on TCP port 3000 by default. To move it to another port, you change the listen directive in the WebTrisul nginx configuration file, set the same port in Web Admin → Manage → App Settings → Web Server, and restart the webtrisuld service. The App Settings value matters because report mailers and real-time features use it to reach the web server.

The problem​

Port 3000 is often already used by another application on the same server, blocked by site policy, or simply not the port your organization allows for management interfaces. You then need WebTrisul to answer on a different port.

The port is set in two places. The bundled nginx web server decides which port browsers connect to. A separate Web Server Port setting in App Settings tells WebTrisul's own background components which port to use. If the two disagree, the login page may load but scheduled report emails and real-time features can fail. This note changes both and explains how they stay in sync.

How it works​

WebTrisul runs behind a bundled nginx web server. nginx accepts browser connections on the port named in the listen directive of /usr/local/share/webtrisul/build/nginx.conf and passes the requests to the WebTrisul application server.

The Web Server Port setting is not used by browsers. WebSockets for real-time features and some scheduled tasks, such as report mailers, use it to connect back to the web server.

Each time the webtrisuld service starts, it reads the port from the first line in nginx.conf that contains the word listen and writes that value into the Web Server Port setting. Inside an LXC or Incus container this copy is skipped, and the value saved in App Settings is used as is. That is why the App Settings value must match the forwarded port when you run Trisul in a container.

Browser ── http://<hub>:<port> ──► nginx  (listen <port>;  in nginx.conf)
                                     │
                                     └──► WebTrisul application server

webtrisuld start:  first "listen" line in nginx.conf ──► App Settings: Web Server Port
                   (skipped inside LXC or Incus containers)

Report mailers, real-time features ──► use Web Server Port

Reference: App Settings: Web Server

Prerequisites​

  • Root or sudo access to the Trisul Hub server.
  • A login to the web interface as admin.
  • The new port number. It must not be in use by another service on the Hub.
  • If Trisul runs in an LXC or Incus container with port forwarding, the port that is forwarded to the container.

Procedure​

Run the shell commands in this procedure as root or with sudo.

Step 1: Change the port in nginx.conf​

  1. Open /usr/local/share/webtrisul/build/nginx.conf in a text editor.

  2. Find the server block. By default it starts like this:

    server {
      listen 3000;
      server_name localhost;

  3. Replace 3000 with your new port. Keep the trailing semicolon, for example listen 8080;.

  4. Save the file.

Check: The listen line you edited must be the first line in the file that contains the word listen. The service start reads the port from that line. The default file has only one such line.

Step 2: Change the Web Server settings​

navigation

👉 Log in as admin and go to Web Admin → Manage → App Settings → Web Server

  1. Fill in the fields:
Field NameDescription
Web Server PortEnter the new port from Step 1. Default is 3000. This port is used by WebSockets for real-time features and by scheduled tasks such as report mailers. If Trisul runs in a Linux container with port forwarding, enter the forwarded port.
Web Server SecurityLeave this set to NONE for the HTTP service. Select SSL only when the web server uses HTTPS. See AN-011.
  1. Click Save.

Outside a container, the restart in Step 3 also copies the port from nginx.conf into Web Server Port. Setting it here keeps the two values aligned before the restart.

Step 3: Restart WebTrisul​

  1. Restart the web service:

    systemctl restart webtrisuld

The restart stops and starts both the WebTrisul application server and nginx.

Verify the result​

  1. In a browser, open http://<hub-address>:<new-port>. The WebTrisul login page loads.
  2. The old address on port 3000 no longer answers, because nginx now listens only on the new port.
  3. Log in as admin and go to Web Admin → Manage → App Settings → Web Server. Web Server Port shows the new port.
  4. If you use scheduled reports, confirm that the next scheduled report email arrives.

Troubleshooting​

The web service does not start and the start output shows "Unable to find SSL port in /usr/local/share/webtrisul/build/nginx.conf". The service could not find any line containing listen in nginx.conf, so it stops before nginx starts. The message says "SSL port" even for the HTTP service. Restore a valid listen <port>; line in the server block and restart webtrisuld.

Web Server Port changes back to the old value after a restart. Outside a container, the service start copies the port from nginx.conf into this setting. If you changed only App Settings, the restart overwrites it. Change the listen directive in nginx.conf (Step 1) and restart.

Web Server Port shows an unexpected value after a restart. The service start uses the first line in nginx.conf that contains the word listen, even if it is a comment. Make sure the active listen directive is the first such line.

Report emails or real-time features fail when Trisul runs in an LXC or Incus container. Inside these containers the port is not copied from nginx.conf. Set Web Server Port to the port forwarded to the container and click Save.

The browser cannot connect on the new port. Check the nginx error log at /usr/local/share/webtrisul/log/nginx.error.log. WebTrisul application logs are in /usr/local/var/log/trisul-hub/webtrisul (production.log for HTTP).

Limitations​

  • This note covers the HTTP service (webtrisuld) and nginx.conf only. The HTTPS service (webtrisulssld) uses a separate file, nginxssl.conf, which listens on port 443 by default. To change the HTTPS port, see AN-011.
  • This note does not cover host firewall changes for the new port.
  • The procedure is verified against the documentation and the product configuration. It has not been lab-tested.
In this page: