Build a local observability workspace first, verify every service, then publish only the web interface
Superlog Community Edition is an open-source observability workspace for OpenTelemetry traces, logs, and metrics. In this guide, we install it from the repository using its documented Node.js, pnpm, and Docker workflow, verify the web, API, and OTLP services locally, and explain the main operational checks. Once the local deployment works, we configure a Localtonet HTTP tunnel for remote access to the web interface. We keep the API and telemetry intake private because the available project documentation does not establish built-in authentication, production TLS configuration, or public-exposure hardening for those endpoints.
📋 What's in this guide
What this Superlog deployment contains
Superlog Community Edition is the open-source edition contained in the Superlog repository. It provides a web application and API, an OpenTelemetry intake proxy, worker processes for incident grouping and background jobs, a PostgreSQL schema, ClickHouse-backed telemetry queries, and interfaces for pluggable investigation runtimes. Its default community agent runner records a local incident summary.
The software accepts OpenTelemetry data across traces, logs, and metrics, then organizes noisy telemetry into incidents. This makes the project more than a standalone log viewer. Several cooperating processes and data services must be available for the complete local workspace to work.
The repository uses a multi-package layout. The web frontend is under apps/web, the HTTP API is under apps/api, the OTLP intake proxy is under apps/proxy, and background workers and agent orchestration are under apps/worker. Database schema and migrations are maintained under packages/db. The repository also includes telemetry fingerprinting helpers under packages/fingerprint.
http://localhost:5173. This is the endpoint we will publish through a Localtonet HTTP tunnel after local verification.
http://localhost:4100. It supports the application, but the available evidence does not document authentication or public API hardening.
http://localhost:4101. Keep this endpoint local unless you have separately verified its security and deployment requirements.
Three HTTP endpoints can create confusion during setup because each has a different purpose. Port 5173 is for the human-facing web application, port 4100 is the application API, and port 4101 is the telemetry intake service. A successful response from one port does not prove that every component is functioning. The browser interface may load while a backend dependency, migration, or worker still has a problem.
| Local endpoint | Purpose | Recommended exposure in this guide |
|---|---|---|
http://localhost:5173 |
Superlog web interface | Publish through a Localtonet HTTP tunnel after local verification |
http://localhost:4100 |
Superlog HTTP API | Keep local because public authentication and hardening are not established by the available documentation |
http://localhost:4101 |
OTLP telemetry intake | Keep local unless separate official guidance establishes a secure remote-ingestion design |
The documented repository quick start is a local development-style workflow based on pnpm dev. The available project evidence does not define a production build, production process manager, stable release deployment procedure, backup policy, high-availability design, or reverse-proxy configuration. This guide therefore documents the supported quick start without presenting it as a production architecture.
Prepare the Superlog host
Run Superlog on a machine that can support its JavaScript workspace and Docker-based local services. The official repository lists Node.js 20 or newer, pnpm 9 or newer, and Docker as prerequisites. The quick start also invokes docker compose, so the Docker installation must provide a working Compose command.
Install these prerequisites using the supported package or installation method for your operating system. The Superlog evidence supplied for this tutorial does not define operating-system-specific installation commands, supported Linux distributions, Windows integration requirements, macOS versions, CPU architecture requirements, or minimum memory and disk capacity. We do not invent those details. If you are working on a constrained device or an unusual architecture, confirm compatibility with the current project documentation before proceeding.
Required software
| Requirement | Documented version | Role in the setup |
|---|---|---|
| Node.js | 20 or newer | Runs the JavaScript and TypeScript applications in the workspace |
| pnpm | 9 or newer | Installs workspace dependencies and starts repository tasks |
| Docker | No minimum version stated | Runs the local containerized stack required by the quick start |
| Docker Compose | No minimum version stated | Processes the repository's docker-compose.yml file |
| Superlog source | Current Community Edition repository checkout | Provides applications, packages, migrations, and stack configuration |
Before downloading dependencies, confirm that your terminal resolves the expected tools:
node --version
pnpm --version
docker --version
docker compose version
The Node.js result must indicate version 20 or newer, and the pnpm result must indicate version 9 or newer. The project does not publish a minimum Docker or Compose version in the evidence used here, so the important initial check is that both Docker and docker compose execute successfully.
Obtain the repository
Download or clone the current Superlog Community Edition repository, then open a terminal in its root directory. You are in the correct directory when repository-level files such as package.json, pnpm-workspace.yaml, and docker-compose.yml are present.
The installation commands below assume the terminal remains in that repository root. Running them from a parent folder or one of the individual application directories can prevent pnpm from recognizing the workspace or prevent Docker Compose from finding its configuration.
The supplied evidence describes installation from the repository, not a pinned stable release. Review the repository's current change history, security policy, configuration, and migration changes before using it with important telemetry. Avoid assuming that a command or configuration from an older checkout remains compatible with a newer one.
Install and start Superlog Community Edition
Superlog's repository quick start defines four ordered actions after the prerequisites and source are available. Install the workspace dependencies first, start the Docker stack second, migrate the database third, and launch the development processes last. Keeping this sequence matters because the application expects its local services and schema to be ready.
Install the workspace dependencies
From the repository root, run pnpm install. This resolves and installs the dependencies defined by the pnpm workspace and its lockfile. Allow the command to complete before starting the local stack.
Start the local Docker stack
Run docker compose up -d from the same repository root. The -d option starts the Compose services in the background, allowing the remaining migration and development commands to run in the terminal.
Apply the database migrations
Run pnpm --filter @superlog/db db:migrate. The filter selects the Superlog database package and invokes its documented migration task. Do not skip this step merely because the containers appear to be running.
Launch the Superlog development services
Run pnpm dev and keep that process active. This starts the repository's development workflow, including the application processes needed for the documented local endpoints.
For convenient copying, the documented sequence is:
pnpm install
docker compose up -d
pnpm --filter @superlog/db db:migrate
pnpm dev
Do not combine initial installation and diagnosis into a single opaque automation script. Running each action separately makes failures easier to identify. A dependency resolution error belongs to the pnpm installation stage, a container startup problem belongs to Docker, a schema error belongs to the migration stage, and a service startup error belongs to pnpm dev.
What successful startup means
The foreground pnpm dev process should remain running while you use Superlog. If that process exits, the services managed by the development task may no longer be available even if the Docker containers continue to run in the background. Conversely, an active development process cannot compensate for unavailable containerized dependencies or a missing database migration.
Startup output can contain messages from several workspace applications because this is a multi-package repository. Focus first on whether the three documented endpoints become reachable. If an endpoint fails, retain the terminal output rather than repeatedly restarting the stack without reading the first error.
A tunnel cannot repair a failed local application. Complete the local checks at localhost first. Only create the Localtonet HTTP tunnel after the browser interface consistently loads on the machine running our client.
Verify the local Superlog services
Verification should proceed from the user-facing interface to its supporting endpoints. Keep pnpm dev running, open a browser on the Superlog host, and visit http://localhost:5173. The page should load from the local machine without any Localtonet tunnel involved.
Next, confirm that the API address http://localhost:4100 is reachable from the same host. The exact browser response, route structure, and health-check path are not established by the supplied project evidence, so do not assume that the root path must display a particular JSON object or status page. The reliable checks are that the process is listening and that the web application can communicate with its backend during normal use.
The OTLP intake service is documented at http://localhost:4101. OTLP is intended for telemetry clients, so opening its root address in a browser is not necessarily a meaningful end-to-end ingestion test. The supplied evidence does not specify an OTLP health route, protocol options, headers, authentication variables, or a sample collector configuration. We therefore do not fabricate a telemetry submission command. Use a project-supported OpenTelemetry configuration when you move from workspace installation to application instrumentation.
http://localhost:5173 on the host. This is the target that must work before remote access is configured.
pnpm dev terminal. Backend or worker failures may appear there even when the initial page shell loads.
pnpm typecheck for development validation. It can help identify source-level issues after local changes.
To run the repository's documented typechecking task, use:
pnpm typecheckA successful typecheck is useful, but it is not a replacement for runtime verification. It does not prove that Docker dependencies started, migrations completed, ports are available, or the browser can communicate with the API.
Use a clean verification boundary
Test from the same machine first. If http://localhost:5173 does not load locally, stop and fix Superlog. If it loads locally but the future public URL does not, investigate the Localtonet client, tunnel state, or local target. This separation prevents application failures from being mistaken for tunnel failures.
Also remember that localhost is relative to the process using it. In this workflow, our Localtonet client should run on the same host as Superlog, making 127.0.0.1:5173 an appropriate local target. If our client runs inside a separate container, virtual machine, or different physical device, its own loopback address will not refer to the Superlog host. In that topology, use an address reachable from the client and verify it locally before creating the tunnel.
Operate the local stack predictably
The documented quick start has two runtime layers. Docker Compose starts the local container stack in detached mode, while pnpm dev runs the development workspace in the foreground. Treat them separately during maintenance.
To stop the foreground development workflow, return to the terminal running pnpm dev and interrupt it normally. The Docker containers started with detached mode may continue running after that foreground command stops. Use the Docker tooling appropriate for your environment when inspecting or stopping those containers. The supplied Superlog quick start does not document a project-specific shutdown, reset, backup, or destructive cleanup procedure, so this guide does not prescribe one.
For a routine restart without changing source or dependencies, ensure the Docker stack is available, confirm migrations are current for the checked-out code, and run pnpm dev. After pulling or downloading a newer repository revision, review changed dependencies and migrations before startup. Re-run the documented dependency installation and migration tasks when the updated project requires them.
Be cautious with data operations
Observability systems can accumulate substantial data, and database resets can remove incident and telemetry history. The current evidence does not define Superlog Community Edition backup, retention, restore, or schema rollback procedures. Do not delete Docker volumes, database files, or migration state as a generic troubleshooting step unless you understand the consequences and have a recovery plan.
Similarly, the evidence does not state minimum disk capacity or automatic retention defaults. Monitor the host's available storage using your operating system and Docker administration tools. When telemetry ingestion is enabled, storage usage can become an operational concern even if the web application itself remains responsive.
Keep the tunnel lifecycle separate
A Localtonet tunnel exists independently from the Superlog development process. Creating a tunnel does not start Superlog, and starting Superlog does not automatically start a tunnel. Remote access requires all of the following to remain true:
- The required Docker services are available.
- The Superlog development workflow is running.
- The web interface is reachable at the configured local target.
- Our Localtonet client is connected on a device that can reach that target.
- The selected HTTP tunnel has been started.
If any layer stops, the public URL may become unavailable or return an application error. This layered model is useful during incident diagnosis because each condition can be tested independently.
Publish the Superlog web interface with a Localtonet HTTP tunnel
Once http://localhost:5173 works reliably, use a Localtonet HTTP tunnel to make that interface reachable through a public URL. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.
Install and run our client on the Superlog host whenever possible. That gives the client direct access to the loopback service on port 5173. If the client must run elsewhere, it needs network access to the Superlog host, and the target IP address must reflect that topology rather than using the client's own loopback interface.
Current client installation choices and available relay server codes can vary. Obtain them from the current Localtonet dashboard or documentation rather than copying a token, server code, or region from another deployment. Device authentication tokens are device-specific secrets and must never be placed in scripts, screenshots, public issue reports, or article examples.
Install and run our Localtonet client
Install the Localtonet client for the operating system on the machine that can reach the Superlog web interface. Keep the client running so it can establish its outbound relay connection.
Authenticate or select the Superlog device
Use the device-specific authentication token associated with the client that will run this tunnel. Select the correct device in the dashboard, and do not reveal or reuse its token as public configuration.
Select an available relay server
Choose a server or region currently offered in the Localtonet dashboard. Available values can change and may vary by deployment or plan, so use the live product selection rather than a hardcoded server code.
Create an HTTP tunnel for the web target
Create an HTTP tunnel whose local target is the Superlog web service. When our client is on the same host, use local IP address 127.0.0.1 and port 5173. Do not point this tunnel at the API on port 4100 or the OTLP intake service on port 4101.
Start the tunnel
Start the newly created tunnel from the dashboard. Creation alone does not make a tunnel active. The selected client must be connected and the tunnel must be running before the assigned public URL can reach Superlog.
Test the assigned public URL
Open the assigned address from a separate browser or network and confirm that the Superlog web interface loads. When remote access is no longer required, stop or delete the tunnel from the dashboard.
HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. The corresponding process types are Random Sub Domain, Custom Sub Domain, and Custom Domain, and they serve the same local content at a public HTTPS address. Availability can depend on the current product and plan. Exact custom-domain DNS instructions are intentionally not included because they must be checked against the current Localtonet documentation.
For the current dashboard workflow and field names, consult our HTTP tunnel documentation. The essential target for this tutorial remains the verified Superlog web service at 127.0.0.1:5173.
The public address works only while the selected Localtonet client is connected, the HTTP tunnel is running, and Superlog is listening at the configured local target. A saved tunnel configuration is not the same as an active service.
Secure the remote-access workflow
A local observability interface may contain traces, logs, metrics, incident descriptions, service names, request details, and other operational information. Some telemetry can also contain personal data, internal identifiers, headers, query values, or application payload fragments if instrumentation is not carefully designed. Treat remote access to Superlog as access to sensitive engineering data.
The available Superlog evidence does not establish built-in authentication for the Community Edition web interface, API, or OTLP intake service. It also does not document production TLS configuration, authorization roles, rate limiting, public deployment hardening, or a stable-release deployment process. A public HTTPS tunnel secures the public transport address, but it does not create application-level identity, user roles, or authorization inside Superlog.
Do not treat an unshared subdomain as authentication. Only expose the interface to people authorized to see its telemetry, stop the tunnel when it is not needed, and apply appropriate access controls when your deployment requires persistent availability. Do not recommend public exposure of ports 4100 or 4101 without separate, current security guidance from the project.
Limit what the tunnel can reach
Configure the HTTP tunnel for only 127.0.0.1:5173 when the client and Superlog share a host. Do not create a broad raw-port forwarding arrangement for all three endpoints simply because they are adjacent in the documentation. Each endpoint has a separate role and risk profile.
Keep the API and OTLP intake bound to local or otherwise controlled networks unless you have validated authentication, authorization, rate limits, and protocol-specific protections. Publishing an ingestion endpoint without those controls could allow unauthorized parties to submit telemetry or consume storage and processing capacity. Publishing an internal API could reveal functionality not intended as a user-facing boundary.
Protect Localtonet device tokens
A Localtonet authentication token identifies the client device that runs the tunnel. Store it as a secret. Never commit it to the Superlog repository, place it in a sample configuration file, include it in terminal recordings, or send it with troubleshooting output. If a token may have been exposed, use the current dashboard controls to address the affected device rather than continuing to rely on the same secret.
Use temporary exposure where possible
For debugging, review, or a short demonstration, start the tunnel immediately before the session and stop it afterward. This reduces the period during which the interface is internet-reachable. It also creates a simple operational boundary: local Superlog can remain available to the host while remote access is enabled only when needed.
Review telemetry before ingestion
Remote access security begins before the tunnel. Instrumented applications determine what data reaches the observability system. Review OpenTelemetry attributes, logs, traces, exception messages, and resource metadata for credentials, session tokens, personal information, and proprietary payloads. A secure tunnel does not sanitize data already stored in Superlog.
Troubleshoot installation and tunnel problems
pnpm install fails
Confirm that Node.js is version 20 or newer and pnpm is version 9 or newer. Verify that the terminal is in the repository root and that the workspace files are present. Preserve the original error because it distinguishes network or registry problems from version incompatibility, lockfile issues, or a package installation failure.
Do not work around an installation error by switching package managers. The documented workflow uses pnpm and the repository includes pnpm workspace and lock files. Using a different package manager can produce a dependency layout the project did not document.
docker compose up -d fails
First verify that Docker is running and that docker compose version succeeds. Confirm that docker-compose.yml exists in the current directory. Then inspect the exact Docker error for port conflicts, image download failures, storage problems, permissions, or container startup errors.
The supplied project evidence does not list every container, image version, host-port mapping, or platform-specific Docker requirement. Use the checked-out Compose file as the authority for that revision rather than guessing container names or manually recreating its services.
The migration command fails
Make sure the Docker stack started successfully before running:
pnpm --filter @superlog/db db:migrateConfirm that dependency installation completed and that you are still in the repository root. A migration failure can indicate that the database is not ready, the checked-out application and schema are mismatched, or the database state needs project-specific attention. Do not delete volumes as a first response because that can destroy retained data.
pnpm dev exits or a port is unavailable
Read the earliest reported error in the terminal. Later workspace failures may be consequences of the first failed process. Check whether another application already uses ports 5173, 4100, or 4101. The evidence documents these as the default local endpoints but does not provide supported alternate-port variables, so this guide does not invent environment variable names for changing them.
Also confirm that the migration completed and the Docker dependencies remain available. If source files were modified, run pnpm typecheck to identify TypeScript problems, while remembering that a successful typecheck does not diagnose runtime infrastructure failures.
The web page loads but data or actions fail
A frontend can begin rendering even when the API, workers, database, or telemetry query layer has a problem. Watch the pnpm dev output while reproducing the issue. Confirm that the API endpoint on port 4100 remains reachable from the host and that the Docker stack is still running.
If no telemetry has been configured, an empty workspace does not necessarily indicate a failed installation. Installing Superlog and instrumenting an application are separate tasks. The available evidence does not define a universal OpenTelemetry client configuration, so follow configuration appropriate to the application language and the current Superlog release.
The public URL does not open
Return to the local boundary first. Open http://localhost:5173 on the Superlog host. If it fails, troubleshoot Superlog rather than the tunnel. If it succeeds, check that our client is connected, the correct device token was selected, and the tunnel was explicitly started.
Confirm that the HTTP tunnel points to port 5173. If our client is on the same host, verify the local target is 127.0.0.1. If the client is on another device or isolated inside a container, test whether that environment can actually reach the address assigned to Superlog. Never assume that 127.0.0.1 crosses device, container, or virtual-machine boundaries.
The public page opens but some browser requests fail
Compare behavior between the local URL and the public URL while observing browser developer tools and the Superlog terminal. The available project evidence does not document public-origin configuration, WebSocket behavior, cross-origin settings, base URL variables, or proxy-aware headers. If the application generates absolute local URLs or rejects the public origin, consult current project guidance rather than guessing configuration keys.
The tunnel worked and then became unavailable
Verify all runtime layers. The Superlog development process may have stopped, Docker may have become unavailable, our Localtonet client may have disconnected, or the tunnel may have been stopped. A tunnel remains available only while the selected device is connected and the tunnel is running.
If this is a long-lived deployment, remember that the repository quick start is based on pnpm dev. The supplied evidence does not establish a production supervisor or automatic restart procedure. Choose long-running process controls only after confirming a supported production deployment model for the Superlog revision you use.
Frequently asked questions
What versions of Node.js and pnpm does Superlog require?
The repository quick start requires Node.js 20 or newer and pnpm 9 or newer. It also requires Docker and uses the docker compose command, although no minimum Docker or Compose version is stated in the supplied evidence.
Which command starts Superlog locally?
After installing dependencies, starting the Docker stack, and applying the database migration, run pnpm dev from the repository root. Keep that foreground process running while using the documented local services.
What are the default Superlog ports?
The web interface is at http://localhost:5173, the API is at http://localhost:4100, and OTLP intake is at http://localhost:4101. These endpoints have different roles and should not be exposed as though they were interchangeable.
Which Superlog port should the Localtonet HTTP tunnel target?
Target the web interface on port 5173. If our client runs on the same machine as Superlog, use 127.0.0.1 as the local IP address. Keep the API and OTLP intake endpoints private unless separate current security documentation supports exposing them.
Does creating a Localtonet tunnel make it active immediately?
No. Creating a tunnel saves its configuration, but it must also be started. The selected Localtonet client must remain connected, the tunnel must be running, and Superlog must remain available at the configured local target.
Does the public HTTPS URL add authentication to Superlog?
No. A public HTTPS address protects transport to the public endpoint, but it does not create application accounts, roles, or authorization. The available Superlog evidence does not establish built-in authentication for this Community Edition workflow, so use temporary exposure and appropriate access controls for sensitive deployments.
Can I expose the OTLP intake port with another tunnel?
Localtonet supports HTTP and raw port tunnel families, but this guide does not recommend public exposure of Superlog's OTLP intake. The supplied project evidence does not document authentication, rate limits, public-ingestion hardening, required protocol details, or TLS configuration for that endpoint. Keep it local until current official project guidance defines a secure design.
Is this a production deployment guide?
No. It follows the documented repository quick start, which uses pnpm dev. The available evidence does not establish a production build, process supervisor, backup strategy, stable release procedure, high availability, retention policy, or production security architecture.
Do I need router port forwarding or a public IP address?
No. Our Localtonet client establishes an outbound connection to a relay server. This allows the Superlog web interface to receive a public URL without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Open your verified Superlog workspace with Localtonet
Start Superlog locally, confirm the web interface on port 5173, then create an HTTP tunnel for controlled remote access without configuring inbound router port forwarding.
Get Started Free →
