Skip to main content

Install with Soln

Use the Soln desktop app on the computer that will run Soln. It checks Docker, guides sign-in, obtains the deployment package, and installs the Runtime. After installation, it can also open workspaces, add existing workspaces, and uninstall local ones. The installation flow downloads and verifies Node.js and Cosign and uses the bundled CLI. Soln generates local certificates without OpenSSL. You do not need to install these tools or configure their PATH.

1. Prepare the computer and account​

  1. Follow Host preparation to prepare Docker and encrypted storage for your operating system. Windows also needs virtualization and WSL2. Tenant data remains on this computer.
  2. Have an existing tenant and a tenant member account with tenant.runtime.deployment.manage. Create the tenant in the Control Plane first if necessary.
  3. Ensure the computer can reach the Soln Control Plane, image registry, and the tool and public dependency download addresses shown in the installation log.

Confirming encryption in the installer does not enable disk encryption.

2. Download and open the installer​

On this computer, visit the Soln download page and choose the package for your OS and CPU architecture. macOS has separate Apple silicon and Intel downloads; the current Windows installer is x64. Install and open Soln.

If a download button is unavailable, confirm that the installer for that platform has been published. “Download local deployment package” on the Control Plane Deployment page downloads a package, not the desktop app.

3. Follow the three installer steps​

On the home screen, choose Register more workspaces (or the first-workspace registration button), then Deploy on this computer.

  1. Prepare the environment: click Check Docker. If it is not ready, start Docker Desktop, wait until it has finished starting, and check again.
  2. Sign in to Soln: click Sign in to Soln, sign in to the Control Plane in the browser, and select the tenant. The installer then receives the tenant deployment package automatically. Check the tenant shown. If a local Runtime is already registered, the installer asks you to confirm redeployment; review the Agent credential replacement before confirming.
  3. Choose a location, confirm encryption, and install: step two shows the Deployment location. It defaults to your home directory. Click Change deployment location to choose another disk or folder. Soln checks encryption on the selected disk. When it reports that disk encryption is enabled, continue and click Install. Soln prepares its tools, verifies the release and images, runs migrations, and starts the services. Wait for the log to show completion. Click Start using to open the Runtime.

The default deployment directory is soln-tenant-runtime-<tenant ID> under your home directory. If you select another location, configuration, database, files, and backups stay inside that deployment directory. Soln selects an available local port. The address is usually https://soln-<tenant subdomain>.localhost:8443; use the exact address shown in the installer. If the browser reports an untrusted certificate, follow the installer's certificate trust instructions.

4. Manage existing workspaces​

The Soln home screen lists discovered local workspaces and server workspaces you added manually. Select one and click Open to visit it in your browser. Register more workspaces starts a new deployment.

  • Add existing workspace → Local workspace: select the root directory of a completed deployment, containing .soln/deployment.json. Do not select its data or .soln subdirectory. Adding it records the directory and shows an entry; it does not reinstall or start the containers.
  • Add existing workspace → Server workspace: enter a workspace name and a complete HTTPS address. A domain or IP address is accepted. This saves an access entry; it does not deploy the server workspace locally.
  • Remove workspace: right-click a workspace in the list and confirm. This only removes its home-screen entry. The deployment, database, and files remain, and you can add the workspace again later.
  • Uninstall local workspace: this option appears only for local workspaces. Right-click the workspace and type the quoted workspace name shown in the confirmation dialog. Soln displays Uninstalling, stops and removes that workspace's Docker Compose project, deletes configuration, database, files, and backups inside the selected deployment directory, and attempts to remove its local root certificate. The loading dialog closes automatically when the operation finishes. Keep any data you need beforehand; this cannot be undone. A server workspace cannot be uninstalled from this computer's menu.

Full uninstall requires deployment data in the data subdirectory of the deployment root. Soln refuses deletion if the directory contains unrelated files, data points outside it, or Docker project ownership cannot be verified. Other deployment directories and cached Docker images are outside this removal.

If installation fails​

  • Windows reports a missing virtual machine platform or WSL: follow Windows preparation, restart when requested, and check again.
  • A tool download or checksum check fails: use the exact file and address in the log to diagnose the download, then retry in Soln. Installing a different system Node.js or Cosign version does not replace this verified download.
  • Docker check fails: start Docker Desktop and retry the first step.
  • An image download times out: check connectivity to the registry named in the installation log. After fixing the network, retry installation in the installer; do not re-register the tenant.
  • Disk encryption check fails: enable system disk encryption, then check again. Selecting a confirmation box alone is not enough.
  • Installation completes but the page does not open: check that containers are running, then verify the exact address and local certificate trust.

After installation, see Upgrade and Rollback.

Optional: install from a Linux terminal

The desktop installer is the main path above. For a deliberate terminal installation, first prepare Docker, Node.js 22 or newer, Cosign, and encrypted storage yourself. This route does not use the desktop installer's private tools; OpenSSL is not required. Replace example and the email below with your tenant details:

npm install -g @soln/cli@latest
sl deployment login --base-url https://api.solncn.com --tenant example --email operator@example.com --method email
sl deployment register --dir "$HOME/soln-tenant-runtime" --deployment-target local --runtime-origin https://soln-example.localhost:8443
sl deployment prepare --dir "$HOME/soln-tenant-runtime"
sl install --dir "$HOME/soln-tenant-runtime" --setup-file .soln-install-setup.json --confirm-encrypted-storage --yes
sl status --dir "$HOME/soln-tenant-runtime" --check --json

After success, remove "$HOME/soln-tenant-runtime/.soln-install-setup.json" and run sl deployment logout.