Install Synaplan and Share It Securely with Localtonet

What this Synaplan and Localtonet workflow provides

Synaplan combines a web-based AI chat experience with capabilities such as retrieval-augmented generation over documents, multiple model providers, assistants, tools, approvals, an embeddable website widget, MCP support, and API access. It is distributed under the Apache-2.0 license and can be run on infrastructure under your control.

The installation and remote-access stages should remain separate. First, Docker starts Synaplan and makes its web interface available on the local machine. You then open the interface locally, wait for the stack to become ready, sign in, and confirm that the application works. Only after those checks pass should you create a public HTTP tunnel.

With Localtonet, our client application establishes an outbound connection from the device running, or able to reach, Synaplan to one of our relay servers. The tunnel then provides a public HTTPS address for the local HTTP service. This avoids requiring an inbound router port-forwarding rule, a public IP address, firewall changes, or a separate VPN configuration.

Why use an HTTP tunnel?

Synaplan’s primary interface is a web application, so an HTTP tunnel is the natural Localtonet tunnel family for this workflow. The tunnel accepts requests at a public HTTPS address and forwards them to the local HTTP endpoint. There is no need to expose Synaplan’s database, cache, vector database, or other internal containers individually.

This is an important boundary. A remote user needs the web application endpoint, not direct access to every service in the Compose network. Publishing only the intended web interface keeps the external surface smaller and makes troubleshooting simpler.

Development quickstart versus production deployment

Prerequisites and planning

For the repository quickstart, prepare a machine with Git, Docker, Docker Compose support, and Make. Docker Desktop can provide Docker and Compose on supported desktop systems. Start Docker Desktop before running the Synaplan commands. On a Linux host, ensure Docker Engine and Docker Compose v2 are installed and that your user can run Docker commands according to your local administration policy.

The complete stack pulls multiple container images, so installation time depends on the machine, storage, and network connection. A status page can appear before every service is fully ready. Treat the ability to load the status page as an early startup signal, not proof that every application feature is operational.

The documented production deployment has more explicit resource requirements. Its cloud-AI profile requires at least 4 vCPUs, 8 GB of RAM, and 30 GB of free disk space. The optional local-AI profile requires at least 16 GB of RAM and substantially more disk capacity. Optional components can add further requirements. These figures belong to the production contract, not a promise that every workload will use a fixed amount of resources.

What to decide before installation

• Evaluation or production: use the repository quickstart for a first local evaluation. Use the documented production contract when you need pinned releases, persistent deployment data, backups, and generated secrets.
• Cloud or local models: Synaplan can connect to external AI providers, while local models are an optional deployment choice. Provider setup and model availability are separate from publishing the web interface.
• Who will have access: decide whether the tunnel is for your own temporary access, a small authorized team, or a longer-lived service.
• Where Localtonet runs: install our client on the Synaplan host when possible, or on another device that can reach the selected local endpoint.
• Which local port is active: use port 5173 for the documented repository quickstart or port 8000 for the default production binding.

Install Synaplan with Docker

Option 1: Repository quickstart with Make

This path is the clearest way to evaluate Synaplan locally because it follows the project’s quickstart and exposes the startup status screen. Run the following commands in a terminal:

git clone https://github.com/metadist/synaplan.git
cd synaplan
make up

The clone command downloads the repository into a directory named synaplan. The second command changes into that directory. The make up target starts the Docker-based stack and brings up the status interface.

Open the following address on the same machine:

http://localhost:5173

Synaplan’s status screen reports boot progress and transitions to the application when the stack is ready. Image downloads and initialization can take longer on the first run, so wait for the application rather than repeatedly restarting the containers.

Option 2: Start the repository checkout with Docker Compose

If Make is unavailable but Docker Compose v2 is present, the documented checkout can also be started directly:

git clone https://github.com/metadist/synaplan.git
cd synaplan
docker compose up -d

The -d option starts the containers in detached mode. Open http://localhost:5173 after starting the stack. In this path, the page may remain quiet while images finish pulling, so use Docker Compose status and logs if startup appears stalled.

docker compose ps
docker compose logs

These are standard Docker Compose inspection commands. The first shows container state, while the second displays stack logs. Avoid copying logs into public support channels without reviewing them for email addresses, file names, provider information, or other deployment details.

Option 3: Use the production deployment contract

The repository quickstart launches a development-oriented stack that includes source-build services and development tools. For a production installation on a Linux server, Synaplan provides a separate single-node contract in the repository’s deploy/ directory. It uses published images rather than source bind mounts and requires a pinned release version.

Begin from a cloned Synaplan repository and create the deployment environment file:

cp deploy/selfhost.env.example deploy/.env

Edit deploy/.env and set a published immutable semantic version in SYNAPLAN_VERSION. Also configure the public URL expected by Synaplan and decide how the first administrator will be created. The production documentation supports either setting the bootstrap administrator variables or leaving both administrator variables empty to use the first-run setup wizard.

After reviewing the environment file, run the documented production sequence:

deploy/scripts/prepare.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml pull
deploy/scripts/validate-release.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d
deploy/scripts/smoke-test.sh

The preparation script generates deployment secrets on first start and writes them to deploy/data/secrets.env. That file is authoritative for the deployment and is required for restoration. Protect it with the same care as the application database and include it in the deployment’s protected backup process.

By default, only the production web service binds a host port, at 127.0.0.1:8000. Internal services such as MariaDB, Redis, Qdrant, and other components remain on the Compose network. This default is well suited to a Localtonet client running on the same host because the client can target the loopback web endpoint without publishing internal service ports.

Complete first-run configuration and secure the account

For the quickstart, sign in with the documented demonstration account only while the instance remains local:

Email: admin@synaplan.com
Password: admin123

Change the password immediately. Use a unique password that is not shared with any other service. If the instance will serve multiple people, create individual accounts rather than distributing one administrator login. Administrator access should be limited to users who actually need to configure providers, models, integrations, or system-wide settings.

The first-run flow also allows you to connect an AI provider. Provider credentials are independent of Localtonet. Store them only in the Synaplan configuration area intended for provider keys, and never place them in the tunnel target, a public URL, client command, or article example.

Security checklist before remote access

• Replace the documented demonstration password.
• Confirm that only intended users have accounts.
• Keep administrator privileges separate from normal chat usage where practical.
• Review uploaded documents and knowledge collections before inviting other users.
• Confirm that model-provider keys are stored in the intended application settings.
• Do not expose database, cache, vector, mail-testing, or administration utility ports.
• Back up production data and deploy/data/secrets.env using the project’s documented lifecycle process.
• Start the public tunnel only when the local application has passed verification.

Be careful with application URL assumptions

Some web applications need an externally visible base URL for redirects, cookies, generated links, integrations, or webhook callbacks. The supplied Synaplan quickstart evidence does not establish the exact configuration required for every remote URL scenario. Test sign-in, navigation, uploads, chat, and any integration you plan to use through the assigned public address.

Do not assume that mobile applications, messaging integrations, widgets, webhooks, or third-party callbacks automatically work merely because the main web interface is reachable. Their URL, authentication, and callback requirements must be checked against the current Synaplan documentation for the specific feature.

Verify Synaplan locally before creating a tunnel

Local verification separates application problems from networking problems. If the interface does not work on the host, adding a public tunnel cannot repair it. Complete the checks below from the machine running Synaplan.

Check the expected URL

For the repository quickstart, open:

http://localhost:5173

For the production contract with its default binding, open:

http://127.0.0.1:8000

A successful check should return the Synaplan status page, setup wizard, sign-in screen, or application interface, depending on installation state. A connection-refused message usually means no process is listening on that address and port. A loading status page usually means the front-end endpoint is responding while other services continue to initialize.

Inspect Docker state

From the directory containing the active Compose configuration, use:

docker compose ps
docker compose logs

Confirm that the expected containers exist and are not continuously restarting. If a service fails, inspect its relevant log output rather than repeatedly running the installation command. Common causes include an unavailable Docker daemon, insufficient memory or disk space, failed image downloads, a port already in use, and incomplete initialization.

Perform an application-level test

Loading a sign-in page proves only that the web endpoint responds. Continue with a basic application test:

1. Sign in with the intended account.
2. Confirm that the main application loads without a recurring error.
3. Open the administration or provider area needed for your deployment.
4. If an AI provider is configured, submit a harmless test prompt.
5. Sign out and sign in again using the new password.

If provider-backed chat fails while the interface works, treat that as an application or provider configuration issue. The HTTP tunnel only forwards web traffic and does not supply model credentials or repair provider connectivity.

Share Synaplan with a Localtonet HTTP tunnel

Once Synaplan works locally and the demonstration credentials have been replaced, install and run the Localtonet client on the device that can reach the web interface. The simplest arrangement is to run our client directly on the Synaplan host. In that case, a service bound to loopback can be targeted through 127.0.0.1.

If our client runs on a different device, 127.0.0.1 refers to that second device, not to the Synaplan server. Synaplan must then listen on an address reachable from the Localtonet client, and the target must use the Synaplan host’s reachable private address. Changing a service binding can affect network exposure, so apply host firewall rules and local access controls deliberately.

These targets are based on the documented default endpoints. If you changed the Compose configuration or host binding, use the address that passed your local verification instead.

Configure the HTTP tunnel

For current dashboard details, consult our Localtonet tunnel documentation. Do not copy a token or relay code from someone else’s configuration. Tokens identify specific client devices, and current relay choices must come from your own dashboard.

Test the public path safely

Open the assigned public URL in a private browser window or on a device outside the Synaplan host. This avoids accidentally relying on an existing administrator session. The expected result is the Synaplan sign-in or setup interface, not an automatically authenticated administrator page.

Sign in with a non-administrator account if one is appropriate for the intended users. Test the operations you plan to share, such as opening chat, viewing authorized files, or submitting a test prompt. If you intend to test a widget or integration, validate it separately because the main interface working does not prove that every callback or embedded-client requirement is satisfied.

Routine operation, backups, updates, and shutdown

Starting and stopping remote access

The Synaplan application and the Localtonet tunnel have independent lifecycles. Synaplan can remain running locally while its tunnel is stopped. Likewise, a configured tunnel cannot serve the application if the Synaplan containers are stopped or our selected client is disconnected.

Stop the tunnel when a temporary review or demonstration ends. Delete it if the configuration is no longer needed. Stopping the tunnel removes public reachability through that tunnel but does not delete Synaplan data or stop its Docker containers.

Stopping the repository stack

If you started the repository checkout with Docker Compose, the standard command to stop and remove its running containers is:

docker compose down

Run it from the same project directory and against the same Compose configuration used to start the stack. Do not add volume-removal options unless you understand exactly which persistent data they delete.

Production data and backups

The production contract keeps database, cache, vector, upload, model, backup, and secret data beneath deploy/data/. Its documented backup lifecycle uses preparation and completion hooks so database and vector snapshots are consistent:

deploy/scripts/pre-backup.sh
# Capture deploy/data with your backup system.
deploy/scripts/post-backup.sh

The pre-backup hook pauses writers and prepares consistent data, while the post-backup hook resumes normal operation. A production backup must include deploy/data/secrets.env. Restoring a database without the corresponding generated secrets can leave the restored data unusable.

Updates

A Git checkout can change significantly over time, while the production contract is designed around pinned immutable release versions. Before updating, read the release notes and the project’s current self-hosting update instructions. Back up the deployment, confirm resource requirements, and avoid the mutable latest tag.

After any update, repeat both verification layers. First test the local endpoint. Then start or retest the Localtonet tunnel and verify the public path in a fresh browser session. This catches application migration problems separately from tunnel connectivity problems.

Troubleshooting Synaplan and Localtonet

The Docker command cannot connect to the daemon

Start Docker Desktop or the Docker Engine service, then retry. Confirm that the current user is permitted to use Docker. This is a host installation issue and should be resolved before investigating Synaplan containers.

Port 5173 or 8000 is already in use

Another process may already be bound to the required host port. Identify the conflicting service using your operating system’s network tools and decide which application should own the port. Do not arbitrarily change the Synaplan port without also updating local verification and the Localtonet tunnel target.

The status page loads but Synaplan never becomes ready

Run docker compose ps and inspect docker compose logs. Look for failed image pulls, repeating container restarts, storage errors, or resource exhaustion. The status endpoint responding means only that part of the stack is reachable.

The local page works but the public URL does not

Check the Localtonet client, selected device token, tunnel status, local target, and port. Confirm that the tunnel was started rather than merely created. If our client runs on another device, do not use 127.0.0.1 unless Synaplan also runs on that same device.

The public page opens, but login or navigation behaves unexpectedly

Retest in a private browser window and inspect whether the application redirects to a local hostname or an unexpected base address. The exact public-base-URL configuration for every Synaplan deployment is not established by the quickstart evidence supplied for this guide. Review the current Synaplan deployment documentation before changing production URL or cookie settings.

Chat fails while the web interface remains available

This usually points to provider credentials, provider connectivity, model selection, or an application service problem rather than the HTTP tunnel. Test the same action through the local URL. If it fails locally too, diagnose Synaplan and its configured AI provider first.

The tunnel disconnects intermittently

A Localtonet tunnel is available only while the selected client device remains connected and the tunnel is running. Check whether the host is sleeping, restarting, losing internet access, or stopping the client process. Also confirm that Synaplan remains healthy at the local target during the same period.

A remote user can see more data than expected

Stop the tunnel immediately, then review Synaplan users, roles, shared files, assistants, and knowledge access. Tunnel connectivity does not determine application-level authorization. Remove unintended access, rotate affected credentials where appropriate, and retest with a non-administrator account before restarting the tunnel.

Frequently asked questions