tesseract

tesseract is a Docker-based cloud development environments that lets you create and manage isolated development environments. it is created because existing solutions are overengineered and missing things that i need.

tesseract was created because I needed a machine to test my other projects without polluting my machine's global environment with project dependencies such as JDKs and other tools. As some of you reading this can relate, I like to overengineer solutions to my problem, which is why I decided to build a container-based development environment for myself.

tesseract is not complete - it does not support multiuser and therefore no authentication system is currently in place. tesseract is designed to be used in an internal high-trust environment (such as a tailnet) where exposure to the machine is limited. there is also no automated testing in place as i do not want to waste more time than i need to on this project.

i am open to feature requests. however, limited time/effort will be spent on this project because unfortunately there are only 24 hours in a day.

---

Documentation

• Features
• Installation
• Running tesseract
• Configuration
• User guide
  • Creating a template
  • Creating a workspace
  • Port forwarding
  • SSH access
  • Docker runtime
  • Data backup

Features

• Create isolated development environments through the web dashboard
• Create templates to reuse and recreate environments easily
• Built-in SSH, HTTP, and WebSocket port forwarding
• Subdomain support for workspaces
• Train multiple machine learning models at the same time via nvidia container toolkit

Installation

Important

Before installing tesseract, make sure that your machine has docker installed.

Using the installation script

Run the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/kennethnym/tesseract/refs/heads/master/scripts/install.sh)"

The installation script will install tesseract to /opt/tesseract/. After the script finishes, update the "hostName" config in /opt/tesseract/config.json

Manual installation

1. Download the appropriate binary from the releases page.
2. Extract the file to wherever you want (/opt/tesseract is used for the installation script)
3. Create a file named config.json and paste the content below
4. Update the "hostName" config to the host name of the server running tesseract (e.g. tesseract.myserver.lab)

Content of config.json:

{
  "port": 80,
  "databasePath": "./data.sqlite",
  "hostName": "HOSTNAME",
  "debug": false
}

Running tesseract

To start tesseract, run the tesseract binary, which runs tesseract in foreground.

You can also run tesseract in the background:

cd /opt/tesseract
nohup ./tesseract > ~/tesseract.log 2>&1 &

Write down the PID so that you can kill it later.

Uninstallation

Remove /opt/tesseract or the directory containing the tesseract binary and related files.

Configuration

A config.json must be present in /opt/tesseract. It contains configurable options for tesseract:

• port: which port tesseract should be listening on. The default is 8080.
• databasePath (required): relative path (relative to the binary) to where the SQLite database is located.
• hostName (required): the host name hosting tesseract.

User guide

Tesseract uses Docker under-the-hood to manage all your development environments, called workspaces. Each workspace is provisioned by an image which is built from a template. A template defines the steps to set up a workspace using a Dockerfile. Tesseract provides base templates out of the box that you can then customize to suit your needs.

Creating a template

To start, first head to the "Templates" section and create a new template by clicking on the "New Template" button:

You should see a dialog:

To start from a base template, click on the "Base template" dropdown, and select the base template you want to start from. Once you are satisfied, hit "Create", and you should be greeted with the template editor. Go ahead and select " Dockerfile" on the left:

If you selected a base template, then you should see some content in the editor. For example, in the screenshot above, the "Fedora 40 with OpenSSH Server" was selected, which configures a workspace with an OpenSSH server to enable SSH access.

You can now start editing the template. tesseract will auto save any changes you save. To build a template, click on the "Build button", which should present you with a build dialog:

Image name is self-explanatory. Keep in mind that if you provide an existing image name, the existing image will be overwritten.

Build arguments allow you to provide argument values for ARGs you defined in your template.

Once you are happy, click on "Build template". The dialog should disappear, and the "Build output" panel should appear below the editor:

Creating a workspace

Once an image is built from a template, you can now create a workspace! Head to the workspaces page, and click on the " New workspace" button. You should be presented with the following dialog:

Here, you give your workspace a name, as well as the image to bootstrap the workspace. The Docker runtime allows you to pick a Docker runtime that should be used to run this workspace. For example, if you want docker-in-docker in your workspace, you should select sysbox-runc as the runtime.

Port forwarding

tesseract provides a built-in proxy that enables both HTTP/WebSocket port forwarding via a subdomain under the host on which tesseract is deployed. To open a port, open the workspace info dialog, and switch to the "Forwarded Ports" tab:

Click on "Add port":

For "subdomain", enter a subdomain that you want to forward the port to. For example, you can forward port 80 to the web subdomain. Port 80 of the workspace is now accessible via *.web.myhost.com, where myhost.com is where you are hosting tesseract.

SSH access

If a workspace has OpenSSH server installed and running, tesseract will automatically expose that under a randomly assigned SSH port. To access the workspace, SSH using host IP/name and the provided port.

Docker runtime

To use a Docker runtime to run your workspaces, you need to first ensure that the runtime is set up and installed on your host machine. Below is a table that lists some Docker runtimes and what feature they provide:

Name	Description
sysbox	Enables isolated Docker in workspaces
nvidia-container-toolkit	Enables nvidia GPU access in workspaces

Warning

I don't have access to an nvidia machine to verify whether nvidia-container-toolkit works well with tesseract, but it should work on paper. Please donate to my kofi or GitHub sponsor if you want me to test it out.

Data backup

To back up tesseract's data, back up data.sqlite. By default it sits next to the tesseract binary, but if you specified a different path in config.json, follow the path and back up data.sqlite.

Important

This does NOT backup workspace data!