194 lines
8.3 KiB
Markdown
194 lines
8.3 KiB
Markdown
# 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](#features)
|
|
- [Installation](#installation)
|
|
- [Running tesseract](#running-tesseract)
|
|
- [Configuration](#configuration)
|
|
- [User guide](#user-guide)
|
|
- [Creating a template](#creating-a-template)
|
|
- [Creating a workspace](#creating-a-workspace)
|
|
- [Port forwarding](#port-forwarding)
|
|
- [SSH access](#ssh-access)
|
|
- [Docker runtime](#docker-runtime)
|
|
- [Data backup](#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](https://github.com/NVIDIA/nvidia-container-toolkit)
|
|
|
|
## Installation
|
|
|
|
> [!IMPORTANT]
|
|
> Before installing tesseract, make sure that your machine has docker installed.
|
|
|
|
### Using the installation script
|
|
|
|
Run the following command:
|
|
|
|
```sh
|
|
/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](https://github.com/kennethnym/tesseract/releases/).
|
|
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:
|
|
|
|
```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:
|
|
|
|
```shell
|
|
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 `ARG`s 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](https://github.com/nestybox/sysbox) | Enables isolated Docker in workspaces |
|
|
| [nvidia-container-toolkit](https://github.com/NVIDIA/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!
|