search

will-moss / isaiah

Self-hostable clone of lazydocker for the web. Manage your Docker fleet with ease
MIT License
86 stars 3 forks source link
docker self-hosted

readme

Isaiah

Self-hostable clone of lazydocker for the web.
Manage your Docker fleet with ease

Table of Contents - Install - Configure

Table of Contents

Introduction

Isaiah is a self-hostable service that enables you to manage all your Docker resources on a remote server. It is an attempt at recreating the lazydocker command-line application from scratch, while making it available as a web application without compromising on the features.

Features

Isaiah has all these features implemented :

On top of these, one may appreciate the following characteristics :

For more information, read about Configuration and Deployment.

Deployment and Examples

Deploy with Docker

You can run Isaiah with Docker on the command line very quickly.

You can use the following commands :

# Create a .env file
touch .env

# Edit .env file ...

# Option 1 : Run Isaiah attached to the terminal (useful for debugging)
docker run \
  --env-file .env \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p <YOUR-PORT-MAPPING> \
  mosswill/isaiah

# Option 2 : Run Isaiah as a daemon
docker run \
  -d \
  --env-file .env \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p <YOUR-PORT-MAPPING> \
  mosswill/isaiah

# Option 3 : Quick run with default settings
docker run -v /var/run/docker.sock:/var/run/docker.sock:ro -p 3000:3000 mosswill/isaiah

Deploy with Docker Compose

To help you get started quickly, multiple example docker-compose files are located in the "examples/" directory.

Here's a description of every example :

When your docker-compose file is on point, you can use the following commands :

# Option 1 : Run Isaiah in the current terminal (useful for debugging)
docker-compose up

# Option 2 : Run Isaiah in a detached terminal (most common)
docker-compose up -d

# Show the logs written by Isaiah (useful for debugging)
docker logs <NAME-OF-YOUR-CONTAINER>

Warning : Always make sure that your Docker Unix socket is mounted, else Isaiah won't be able to communicate with the Docker API.

Deploy as a standalone application

You can deploy Isaiah as a standalone application, either by downloading an existing binary that fits your architecture, or by building the binary yourself on your machine.

Using an existing binary

An install script was created to help you install Isaiah in one line, from your terminal :

As always, check the content of every file you pipe in bash

curl https://raw.githubusercontent.com/will-moss/isaiah/master/scripts/remote-install.sh | bash

This script will try to automatically download a binary that matches your operating system and architecture, and put it in your /usr/[local/]bin/ directory to ease running it. Later on, you can run :

# Create a new .env file
touch .env

# Edit .env file ...

# Run Isaiah
isaiah

In case you feel uncomfortable running the install script, you can head to the Releases, find the binary that meets your system, and install it yourself.

Building the binary manually

In this case, make sure that your system meets the following requirements :

When all the prerequisites are met, you can run the following commands in your terminal :

As always, check the content of everything you run inside your terminal

# Retrieve the code
git clone https://github.com/will-moss/isaiah
cd isaiah

# Run the local install script
./scripts/local-install.sh

# Move anywhere else, and create a dedicated directory
cd ~
mkdir isaiah-config
cd isaiah-config

# Create a new .env file
touch .env

# Edit .env file ...

# Option 1 : Run Isaiah in the current terminal
isaiah

# Option 2 : Run Isaiah as a background process
isaiah &

# Option 3 : Run Isaiah using screen
screen -S isaiah
isaiah
<CTRL+A> <D>

# Optional : Remove the cloned repository
# cd <back to the cloned repository>
# rm -rf ./isaiah

The local install script will try to perform a production build on your machine, and move isaiah to your /usr/[local/]bin/ directory to ease running it. In more details, the following actions are performed :

If you encounter any issue during this process, please feel free to tweak the install script or reach out by opening an issue.

Multi-node deployment

Using Isaiah, you can manage multiple nodes with their own distinct Docker resources from a single dashboard.

Before delving into that part, please get familiar with the general information below.

General information

You may find these information useful during your setup and reading :

In other words, one Master acts as a Proxy between the Client and the Agents.
For example, when a Client wants to stop a Docker container inside an Agent, the Client first requests it from Master. Then, Master forwards it to the designated Agent. When the Agent has finished, they reply to Master, and Master forwards that response to the initial Client.

Schematically, it looks like this :

Now that we understand how everything works, let's see how to set up a multi-node deployment.

Setup

First, please ensure the following :

Then, launch Isaiah on each Agent node, and you should see logs indicating whether connection with Master was established. Eventually, you will see Master or The name of your agent in the lower right corner of your screen as agents register.

If encounter any issue, please read the Troubleshoot section.

You may want to note that you don't need to expose ports on the machine / Docker container running Isaiah when it is configured as an Agent.

Multi-host deployment

Using Isaiah, you can manage multiple hosts with their own distinct Docker resources from a single dashboard.

Before delving into that part, please get familiar with the general information below.

General information

The big difference between multi-node and multi-host deployments is that you won't need to install Isaiah on every single node if you are using multi-host. In this setup, Isaiah is installed only on one server, and communicates with other Docker hosts directly over TCP / Unix sockets. It makes it easier to manage multiple remote Docker environments without having to setup Isaiah on all of them.

Please note that, in a multi-host setup, there must be a direct access between the main host (where Isaiah is running) and the other ones. Usually, they should be on the same network, or visible through a secured gateway / VPN / filesystem mount.

Let's see how to set up a multi-host deployment.

Setup

In order to help you get started, a sample file was created.

First, please ensure the following :

Second, please create a docker_hosts file next to Isaiah's executable, using the sample file cited above:

If you're using Docker, you can mount the file at the root of the filesystem, as in :
docker ... -v my_docker_hosts:/docker_hosts ...

Finally, launch Isaiah on the Master host, and you should see logs indicating whether connection with remote hosts was established. Eventually, you will see Master with The name of your host in the lower right corner of your screen.

Forward Proxy Authentication / Trusted SSO

If you wish to deploy Isaiah behind a secure proxy or authentication portal, you must configure Forward Proxy Authentication.

This will enable you to :

Before proceeding, please ensure the following :


For example, if you're using Nginx Proxy Manager (NPM), you should do the following :

  • In the tab "Details"
    • Tick the box "Websockets support"
    • Tick the box "HTTP/2 support"
    • Tick the box "Block common exploits"
    • Tick the box "Force SSL"

  • In the tab "Advanced"
    • In your custom location block, add the lines :
      • proxy_set_header Upgrade $http_upgrade;
      • proxy_set_header Connection "upgrade";

Then, configure Isaiah using the following variables :

By default, Isaiah is configured to work with Authelia out of the box. Hence, you can just set FORWARD_PROXY_AUTHENTICATION_ENABLED to true and be done with it.

If everything was properly set up, you will encounter the following flow :

Configuration

To run Isaiah, you will need to set the following environment variables in a .env file located next to your executable :

Note : Regular environment variables provided on the commandline work too

Parameter Type Description Default
SSL_ENABLED boolean Whether HTTPS should be used in place of HTTP. When configured, Isaiah will look for certificate.pem and key.pem next to the executable for configuring SSL. Note that if Isaiah is behind a proxy that already handles SSL, this should be set to false. False
SERVER_PORT integer The port Isaiah listens on. 3000
SERVER_MAX_READ_SIZE integer The maximum size (in bytes) per message that Isaiah will accept over Websocket. Note that, in a multi-node deployment, you may need to incrase the value of that setting. (Shouldn't be modified, unless your server randomly restarts the Websocket session for no obvious reason) 100000
AUTHENTICATION_ENABLED boolean Whether a password is required to access Isaiah. (Recommended) True
AUTHENTICATION_SECRET string The master password used to secure your Isaiah instance against malicious actors. one-very-long-and-mysterious-secret
AUTHENTICATION_HASH string The master password's hash (sha256 format) used to secure your Isaiah instance against malicious actors. Use this setting instead of AUTHENTICATION_SECRET if you feel uncomfortable providing a cleartext password. Empty
DISPLAY_CONFIRMATIONS boolean Whether the web interface should display a confirmation message after every succesful operation. True
COLUMNS_CONTAINERS string Comma-separated list of fields to display in the Containers panel. (Case-sensitive) (Available: ID, State, ExitCode, Name, Image, Created) State,ExitCode,Name,Image
COLUMNS_IMAGES string Comma-separated list of fields to display in the Images panel. (Case-sensitive) (Available: ID, Name, Version, Size) Name,Version,Size
COLUMNS_VOLUMES string Comma-separated list of fields to display in the Volumes panel. (Case-sensitive) (Available: Name, Driver, MountPoint) Driver,Name
COLUMNS_NETWORKS string Comma-separated list of fields to display in the Networks panel. (Case-sensitive) (Available: ID, Name, Driver) Driver,Name
SORTBY_CONTAINERS string Field used to sort the rows in the Containers panel. (Case-sensitive) (Available: ID, State, ExitCode, Name, Image, Created) Empty
SORTBY_IMAGES string Field used to sort the rows in the Images panel. (Case-sensitive) (Available: ID, Name, Version, Size) Empty
SORTBY_VOLUMES string Field used to sort the rows in the Volumes panel. (Case-sensitive) (Available: Name, Driver, MountPoint) Empty
SORTBY_NETWORKS string Field used to sort the rows in the Networks panel. (Case-sensitive) (Available: Id, Name, Driver) Empty
CONTAINER_HEALTH_STYLE string Style used to display the containers' health state. (Available: long, short, icon) long
CONTAINER_LOGS_TAIL integer Number of lines to retrieve when requesting the last container logs 50
CONTAINER_LOGS_SINCE string The amount of time from now to use for retrieving the last container logs 60m
TTY_SERVER_COMMAND string The command used to spawn a new shell inside the server where Isaiah is running /bin/sh -i
TTY_CONTAINER_COMMAND string The command used to spawn a new shell inside the containers that Isaiah manages /bin/sh -c eval $(grep ^$(id -un): /etc/passwd \| cut -d : -f 7-) -i
CUSTOM_DOCKER_HOST string The host to use in place of the one defined by the DOCKER_HOST default variable Empty
CUSTOM_DOCKER_CONTEXT string The Docker context to use in place of the current Docker context set on the system Empty
SKIP_VERIFICATIONS boolean Whether Isaiah should skip startup verification checks before running the HTTP(S) server. (Not recommended) False
SERVER_ROLE string For multi-node deployments only. The role of the current instance of Isaiah. Can be either Master or Agent and is case-sensitive. Master
MASTER_HOST string For multi-node deployments only. The host used to reach the Master node, specifying the IP address or the hostname, and the port if applicable (e.g. my-server.tld:3000). Empty
MASTER_SECRET string For multi-node deployments only. The secret password used to authenticate on the Master node. Note that it should equal the AUTHENTICATION_SECRET setting on the Master node. Empty
AGENT_NAME string For multi-node deployments only. The name associated with the Agent node as it is displayed on the web interface. It should be unique for each Agent. Empty
MULTI_HOST_ENABLED boolean Whether Isaiah should be run in multi-host mode. When enabled, make sure to have your docker_hosts file next to the executable. False
FORWARD_PROXY_AUTHENTICATION_ENABLED boolean Whether Isaiah should accept authentication headers from a forward proxy. False
FORWARD_PROXY_AUTHENTICATION_HEADER_KEY string The name of the authentication header sent by the forward proxy after a succesful authentication. Remote-User
FORWARD_PROXY_AUTHENTICATION_HEADER_VALUE string The value accepted by Isaiah for the authentication header. Using * means that all values are accepted (except emptiness). This parameter can be used to enforce that only a specific user or group can access Isaiah (e.g. admins or john). *

Note : Boolean values are case-insensitive, and can be represented via "ON" / "OFF" / "TRUE" / "FALSE" / 0 / 1.

Note : To sort rows in reverse using the SORTBY_ parameters, prepend your field with the minus symbol, as in -Name

Note : Use either AUTHENTICATION_SECRET or AUTHENTICATION_HASH but not both at the same time.

Note : You can generate a sha256 hash using an online tool, or using the following commands : On OSX : echo -n your-secret | shasum -a 256 On Linux : echo -n your-secret | sha256sum

Additionally, once Isaiah is fully set up and running, you can open the Parameters Manager by pressing the X key. Using this interface, you can toggle the following options based on your preferences :

Parameter Description
enableMenuPrompt Whether an extra prompt should warn you before trying to stop / pause / restart a Docker container.
enableLogLinesWrap Whether log lines streamed from Docker containers should be wrapped (as opposed to extend beyond your screen).
enableTimestampDisplay Whether log lines' timestamps coming from Docker containers should be displayed.
enableOverviewOnLaunch Whether an overview panel should show first before anything when launching Isaiah in your browser.
enableLogLinesStrippedBackground Whether alternated log lines should have a brighter background to enhance readability.
enableJumpFuzzySearch Whether, in Jump mode, fuzzy search should be used, as opposed to default substring search.

Note : You must have Isaiah open in your browser and be authenticated to access these options. Once set up, these options will be saved to your localStorage.

Theming

You can customize Isaiah's web interface using your own custom CSS. At runtime, Isaiah will look for a file named custom.css right next to the executable. If this file exists, it will be loaded in your browser and it will override any existing CSS rule.

In order to help you get started, a sample file was created. It shows how to modify the CSS variables responsible for the colors of the interface. (All the values are the ones used by default) You can copy that file, update it, and rename it to custom.css.

If you're using Docker, you should mount a custom.css file at the root of your container's filesystem. Example : docker ... -v my-custom.css:/custom.css ...

Finally, you will find below a table that describes what each CSS color variable means :

Variable Description
color-terminal-background Background of the interface
color-terminal-base Texts of the interface
color-terminal-accent Elements that are interactive or must catch the attention
color-terminal-accent-selected Panel's title when the panel is in focus
color-terminal-hover Panel's rows that are in focus / hover
color-terminal-border Panels' borders color
color-terminal-danger The color used to convey danger / failure
color-terminal-warning Connection indicator when connection is lost
color-terminal-accent-alternative Connection indicator when connection is established
color-terminal-log-row-alternative The color used as background for each odd row in the logs tab
color-terminal-json-key The color used to distinguish keys from values in the inspector when displaying a long configuration
color-terminal-json-value The color used to distinguish values from keys in the inspector when displaying a long configuration
color-terminal-cell-failure Container health state when exited
color-terminal-cell-success Container health state when running
color-terminal-cell-paused Container health state when paused

On a side note, creating custom layouts using only CSS isn't implemented yet as it requires interaction with Javascript. That said, implementing this feature should be quick and simple since the way layouts are managed currently is already modular.

Ultimately, please note that Isaiah already comes with three themes : dawn, moon, and the default one. The first two themes are based on Rosé Pine, and new themes may be implemented later.

Troubleshoot

Should you encounter any issue running Isaiah, please refer to the following common problems with their solutions.

Isaiah is unreachable over HTTP / HTTPS

Please make sure that the following requirements are met :

In any case, the crucial part is Configuration and making sure your Docker / Proxy setup is correct as well.

The emulated shell behaves unconsistently or displays unexpected characters

Please note that the emulated shell works by performing the following steps :

According to this implementation, the remote terminal never receives key presses. It only receives commands.

Also, the following techniques are used to try to enhance the user experience on the web interface :

Therefore it appears that, unless we use a VNC-like solution, the emulation can neither be enhanced nor use keyboard-based features (such as tab completion).

Unless a contributor points the project in the right direction, and as far as my skills go, I personally believe that the current implementation has reached its maximum potential.

I leave here a few ideas that I believe could be implemented, but may require more knowledge, time, testing :

Ultimately, please also note that in a multi-node / multi-host setup, the extra network latency and unexpected buffering from remote terminals may cause additional display artifacts.

An error happens when spawning a new shell on the server / inside a Docker container

The default commands used to spawn a shell, although being more or less standard, may not fit your environment. In this case, please edit the TTY_SERVER_COMMAND and TTY_CONTAINER_COMMAND settings to define a command that works better in your setup.

The connection with the remote server randomly stops or restarts

This is a known incident that happens when the Websocket server receives a data message that exceeds its maximum read size. You should be able to fix that by updating the SERVER_MAX_READ_SIZE setting to a higher value (default is 1024 bytes). This operation shouldn't cause any problem or impact performances.

I can neither click nor use the keyboard, nothing happens

In such a case, please check the icon in the lower right corner. If you see an orange warning symbol, it means that the connection with the server was lost. When the connection is lost, all inputs are disabled, until the connection is reestablished (a new attempt is performed every second).

The interface is stuck loading indefinitely

This incident arises when a crash occurs while inside a shell or performing a Docker command. The quickest "fix" for that is to refresh your browser tab (Ctrl+R/Cmd+R).

The real "fix" (if any) could be to implement a "timeout" (client-side or server-side) after which, the "loading" state is automatically discarded

If you encounter this incident consistently, please reach out by opening an issue so we look deeper into that part

The web interface seems to randomly crash and restart

If you haven't already, please read about the SERVER_MAX_READ_SIZE setting in the Configuration section.

That incident occurs when the Websocket messages sent from the client to the server are too big. The server's reaction to overly large messages sent over Websocket is to close the connection with the client. When that happens, Isaiah (as a client in your browser) automatically reopens a connection with the server, hence explaining the "crash-restart" cycle.

A feature that works on desktop is missing from the mobile user interface

Please note that you can horizontally scroll the mobile controls located in the bottom part of your screen to reveal all of them. If, for any reason, you still encounter a case when a feature is missing on your mobile device, please open an issue indicating the browser you're using, your screen's viewport size, and the model of your phone.

In a multi-node deployment, the agent's registration with master is stuck loading indefinitely

This issue arises when the authentication settings between Master and Agent nodes are incompatible.
To fix it, please make sure that :

Also don't forget to restart your nodes when changing settings.

Something else

Please feel free to open an issue, explaining what happens, and describing your environment.

Security

Due to the very nature of Isaiah, I can't emphasize enough how important it is to harden your server :

Keep in mind that any breach or misconfiguration on your end could allow a malicious actor to fully take over your server.

Disclaimer

I believe that, although we're both in the open-source sphere and have all the best intentions, it is important to state the following :

Ultimately, thanks to the people behind lazydocker both for the amazing project (that I'm using daily) and for paving the way for Isaiah.

PS : Please also note that Isaiah isn't exactly 100% feature-equivalent with lazydocker (e.g. charts are missing) PS2 : What spurred me to build Isaiah in the first place is a bunch of comments on the Reddit self-hosted community, stating that Portainer and other available solutions were too heavy or hard to use. A Redditor said that having lazydocker over the web would be amazing, so I thought I'd do just that.

Contribute

This is one of my first ever open-source projects, and I'm not a Docker / Github / Docker Hub / Git guru yet.

If you can help in any way, please do! I'm looking forward to learning from you.

From the top of my head, I'm sure there's already improvement to be made on :

Credits

Hey hey ! It's always a good idea to say thank you and mention the people and projects that help us move forward.

Big thanks to the individuals / teams behind these projects :

And don't forget to mention Isaiah if it makes your life easier!