Skip to main content

​
Get connected in minutes

This guide walks you through setting up suSHi and connecting to your first remote machine via the browser-based terminal.
Before starting, ensure you have Docker and Docker Compose installed on your system.

​
Prerequisites

  • Docker and Docker Compose installed
  • A remote machine you want to connect to via SSH
  • SSH credentials (password or private key) for the remote machine

​
Setup suSHi

1

Create the project directory

Set up the directory structure for suSHi:
mkdir sushi-app
cd sushi-app
mkdir -p db/data
sudo chown -R 1001:1001 ./db/data
The db/data directory stores PostgreSQL data with the correct permissions for the Bitnami PostgreSQL image.
2

Create docker-compose.yaml

Create a docker-compose.yaml file in the project directory:
docker-compose.yaml
version: '3.8'

services:
  postgres:
    image: bitnami/postgresql
    container_name: postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: sushi
    volumes:
      - ./db/data:/bitnami/postgresql/data
    restart: always
  
  sushi-backend:
    image: breeze5690/sushi-backend-prod:v1
    ports:
      - "8080:8080"
    environment:
      - SERVER_PORT=8080
      - LOG_LEVEL=Debug
      - JWT_SECRET=secret123
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USER=postgres
      - DB_PASSWORD=postgres
      - DB_NAME=sushi
      - MIGRATE_DB=true
      - GOOGLE_CLIENT_ID=
      - GOOGLE_CLIENT_SECRET=
      - GOOGLE_REDIRECT_URL=http://localhost:8080/api/v1/auth/callback
      - GITHUB_CLIENT_ID=
      - GITHUB_CLIENT_SECRET=
      - GITHUB_REDIRECT_URL=http://localhost:8080/api/v1/auth/callback
    depends_on:
      - postgres
    restart: always
Change JWT_SECRET to a secure random string in production environments.
3

Start the services

Launch suSHi using Docker Compose:
docker compose up -d
Wait for the containers to start. You can check the logs:
docker compose logs -f sushi-backend
Look for the message: Starting server on port 8080
4

Access the web interface

Open your browser and navigate to:
http://localhost:8080
You should see the suSHi homepage with authentication options.

​
Connect to your first machine

1

Authenticate

Click on the OAuth authentication option (Google or GitHub) to sign in.
If you haven’t configured OAuth credentials, you may need to set up OAuth apps. See the Installation guide for details.
2

Add a machine

Once authenticated, navigate to the dashboard and click Add Machine.Fill in the connection details:
  • Host: IP address or hostname of your remote server
  • Port: SSH port (usually 22)
  • Username: Your SSH username
  • Authentication: Choose password or private key
3

Enter credentials

Depending on your authentication method:
  • Password: Enter your SSH password
  • Private Key: Paste your SSH private key
Your private key is encrypted using AES-CFB before being stored in the database.
4

Connect

Click Connect to establish the SSH connection. A browser-based terminal will open with a live connection to your remote machine.You can now execute commands just as you would in a local terminal.

​
Troubleshooting

If you see “connection closed” errors when opening the terminal, you may need to adjust the WebSocket protocol.For local development, edit static/terminal.html (line 95) and change wss:// to ws://.
Only use ws:// (unencrypted) for local development. Always use wss:// in production.
Ensure the db/data directory has the correct permissions:
sudo chown -R 1001:1001 ./db/data
If port 8080 is already in use, modify the port mapping in docker-compose.yaml:
ports:
  - "3000:8080"  # Use port 3000 instead

​
Next steps

Installation guide

Learn about advanced configuration options and OAuth setup.

Add multiple machines

Manage connections to multiple remote servers from one dashboard.

Build docs developers (and LLMs) love

Get started for freeTalk to us