Skip to content

Latest commit

 

History

History
120 lines (88 loc) · 3.89 KB

ARCHITECTURE.md

File metadata and controls

120 lines (88 loc) · 3.89 KB

Internal architecture

Overview

The Stack Desktop app is a ( mac) desktop app capable of running software stacks. It is built in Rust and leverages Tauri as the framework and runtime.

It works alongside a website that provides a catalog of software stacks over at https://stack.lol.

The catalog is a collection of stack bundles which are compressed archives (<name>.stack) each containing a full-fledged software stack. The stack is a collection of software components that work together to provide a specific functionality.

The website is able to notify the app to download and run a software stack from a stack bundle.

The app exposes a secured API that the website can use to notify it to download and run a software stack.

Schema

graph LR
  catalog[Stack Catalog] --> stackBundle[Stack Bundle<br><q>&lt;name&gt;.stack</q>]

  subgraph "Stack Bundle"
    stackBundle --> metadata[Metadata<br><q>stack.yaml</q>]
    stackBundle --> dockerCompose[Docker Compose]
  end

  subgraph "Desktop App"
    stackApp[Stack Desktop] --> stackBundle
    stackApp --> metadata
    stackApp --> dockerCompose
    stackApp --> containers[Containers]
  end

  website[Website] --> catalog
  website --> stackApp

  subgraph "External dependencies"
    docker[Docker Engine]
  end

  docker[Docker Engine] -.-> stackApp
  dockerCompose -.-> docker
  docker --> containers
Loading

API

Security

API Security

The app exposes an API that the website can use to communicate with it. To ensure this communication is secure:

  1. The app generates a self-signed certificate when initializing which is used for HTTPS communication;
  2. API connections are restricted to localhost (127.0.0.1) to prevent external network access;
  3. All API requests require authentication using time-limited JWT tokens;
  4. The website and app share a secret key for mutual authentication;

User Protection

  1. The app is signed and notarized for macOS to verify its authenticity;
  2. Users must explicitly approve downloading and running stacks via confirmation dialogs;
  3. User preferences can be configured for trusted stacks to reduce prompts;

Bundle Security

  1. All stack bundles are digitally signed by the catalog publisher;
  2. Bundle checksums and signatures are verified before extraction;
  3. Downloaded bundles are scanned for potentially malicious content;
  4. Corrupted or tampered bundles are rejected with appropriate error messages;

Container Isolation

  1. Containers run with minimal required privileges by default;
  2. Resource limits (CPU, memory, network) are enforced for all running stacks;
  3. Volume mounts are restricted to designated directories;
  4. Network access for containers is properly segmented and controlled;
  5. The app monitors running containers for unusual behavior;

Diagrams

Run a software stack from a stack bundle

sequenceDiagram
  actor user as User
  participant web as Website
  box grey
    participant app as Stack Desktop
    participant fs as File system
  end

  user->>+web: Click on "Start it now"
  web->>-app: Notify the app
  activate app

  app->>+web: Download the bundle
  web->>-fs: Store the bundle
  activate fs
  Note over fs: Bundle file
  fs-->>app: Read the bundle
  deactivate fs
  app->>fs: Unpack the bundle
  activate fs
  Note over fs: Unpacked directory
  fs-->>app: Read metadata<br>Detect name, flavor
  deactivate fs
  app->>app: Run the stack
  app-->>web: Notify the website

  deactivate app

  link web: Website @ https://stack.lol
  link app: Download @ https://stack.lol/download
Loading