eSim Desktop

A dedicated desktop application wrapper for eSim Cloud, built using Tauri, Vite, and Vanilla TypeScript.

Overview & How It Works

eSim Desktop simplifies the installation and execution of the eSim Cloud environment by providing a "one-click" desktop experience. Rather than requiring users to manually clone repositories and run terminal commands, this application automates the entire process.

When you launch eSim Desktop, it automatically performs a series of startup checks:

1. Docker Check: Verifies that Docker is installed and the Docker daemon is running.
2. Git Check: Ensures Git is installed on the system.
3. Workspace Preparation: Automatically clones the esim-cloud repository to your local machine (if it hasn't been cloned already).
4. Container Management: Checks if the required eSim Docker containers are running. If not, it automatically spins them up using Docker Compose.
5. Health Polling: Waits and polls the backend until it is fully healthy and ready to accept connections.
6. Application Launch: Once everything is ready, it seamlessly loads the local eSim Cloud web interface (http://localhost/) directly inside the desktop window.

If any step fails (e.g., Docker is missing, or the port is blocked), the app provides friendly, actionable error screens with retry buttons.

Key Features

• Automated Environment Setup: Automatically clones the necessary esim-cloud repositories without requiring terminal commands.
• Built-in Docker Management: Automatically detects and spins up the required Docker Compose services in the background.
• Interactive Health Checks: Displays a native splash screen with real-time loading progress and backend health polling.
• Auto-recovery UI: Provides actionable error screens with "Retry" buttons and direct download links if dependencies (like Docker or Git) are missing.
• Desktop Native Experience: Wraps the eSim web application inside a lightweight, fast, and native window utilizing Tauri.

Troubleshooting & Common Errors

If the application fails to start, it will display a specific error screen. Here is what they mean and how to resolve them:

• Docker not found: The application could not detect Docker on your system. You must install Docker Desktop and add it to your system's PATH.
• Docker daemon not running: Docker is installed, but the engine isn't running. Open Docker Desktop manually, wait for the engine to start, and click "Retry" in the app.
• Git not found: Git is required to clone the backend repository. Install Git and ensure it's available in your command line.
• Clone failed: The app failed to download esim-cloud. Check your internet connection or verify if your network blocks GitHub traffic.
• Backend not reachable / Docker Compose failed: The containers failed to start or health checks timed out. This is usually an issue with the Docker containers themselves.
  • Fix: You can refer to the official esim-cloud repository for advanced setup and debugging logs. You may also need to check if port 80 is currently in use by another application.

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js (v16 or higher recommended)
• Rust (required for the Tauri backend)
• Docker Desktop (must be installed and running)
• Git
• For Windows: C++ Build Tools (via Visual Studio Build Tools)
• For Linux/macOS: See Tauri's OS-specific dependencies

Getting Started

1. Install dependencies

   npm install
   # or
   bun install

2. Run in development mode This will start the Vite frontend development server and launch the Tauri backend window.

   npm run tauri dev

Build for Production

To build the executable installer for your platform:

npm run tauri build

The compiled installers (like .exe, .msi, .dmg, or .deb) and executables will be located in the src-tauri/target/release/bundle directory.

Recommended IDE Setup

• VS Code + Tauri + rust-analyzer