# Base-workspace Base-Workspace - is an attempt to use docker as a lightweight Virtual Machine "with batteries included". It can be used on laptop, PC or on a server in cloud via WEB-based interfaces. It has its own UI, browser-based based terminal, file browser, visual job scheduler, and other applications. It can be launched on a remote server over HTTPS with authentication. #### Try it out ``` docker run --name space-1 --user=root -d -p 8020-8030:8020-8030 alnoda/base-workspace ``` ## Contents * [Why this image](#why-this-image) * [Use-cases](#use-cases) * [Features](#features) * [Launch Workspace](#launch-workspace) * [Workspace terminal](#workspace-terminal) * [Multiple workspaces](#multiple-workspaces) * [Open more ports](#open-more-ports) * [Docker in docker](#docker-in-docker) * [Run on remote server](#run-on-remote-server) * [Use Workspace](#use-workspace) * [Install applications](#install-applications) * [Schedule jobs with Cron](#schedule-jobs-with-cron) * [Python](#python) * [Node.js](#node.js) * [Run applications and services inside the workspace](#run-applications-and-services-inside-the-workspace) * [Manage workspaces](#manage-workspaces) * [Start and stop workspaces](#start-and-stop-workspaces) * [Create new workspace image](#create-new-workspace-image) * [Manage workspace images](#manage-workspace-images) * [Save and load workspace images](#save-and-load-workspace-images) * [Move workspace to the cloud](#move-workspace-to-the-cloud) ## Why this image > TL;DR > You can provide your users with many virtual environments, manage just one server, and have less work with server configuration management. Because Docker is not completely suitable to serve this purpose, Base-Workspace tries to cover some of the shortcomings: it has cron set up, supervisord, allows to start multiple processes inside the same container, has docker-in-docker, and some other applications installed, such as Git, Gitflow, wget, nano, vim etc. In addition Base-Workspace has some applications with WEB-UI, which make it easier to scheddule and monitor job executions, browse and exchange files, work with terminal, monitor resources and processes running inside the docker container. For convenience, Base-Workspace has its own WEB UI, which you can use to quickly open in browser the UIs of the applications running inside the workspace. ![base-workspace-presentation](./img/base-workspace.gif) Base-Workspace can be used as isolated environment on local machine, or as alternative to VM on the cloud server. It can run as root, or as default **abc** user that is allowed to use *apt-get*. ## Use-cases VMs are great, but they are too heavy and require way too much resources, even more than enhanced docker containers like this one. There are cases when we need isolation as in VMs, but not all the features and security of VMs. Hence there is no need to pay extra price. A typical example of such use cases are virtual environments to run background jobs, check liveness of services or websites, do all kind of checks, schedule maintenance tasks, have cli to a database, run internal non-critical services, launch WEB-scrapping applications, generate reports, run ETL scripts and many others. Since these jobs are owned by multiple users we need some kind of isolation. Running separate servers for every user would be too cost-inefficient. Most periodic tasks utilize compute resources from time to time, and running the server all the time would be such a waste. It makes more sense to have one server where all these virtual environments are running. Also it easier for sysops to monitor and maintain a single server. Base-workspace is a way to provide isolated environments on a shared server, which is used by multiple users. It is more resource-efficient than VM, it is secure (if running under defualit user), and it is convenient to use, becuause Base-workspace is bootstrapped with many commonly used applications, it has WEB-UI, and users work with it entirely through browser. ## Features Being an extension of [ubuntu-workspace-in-docker](https://github.com/Alnoda/ubuntu-workspace-in-docker), this image has all the features that ubuntu-workspace has. Workspace includes several open-source tools with browser-based GUI: - [**FileBrowser**](./features.md#filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace - **Terminal** - Full-fledged browser-based terminal with Z-shell. - [**Cronicle**](./features.md#cronicle) - task scheduler and runner, with a web based front-end UI. It handles both scheduled, repeating and on-demand jobs, targeting any number of worker servers, with real-time stats and live log viewer. - [**Static File Server**](./features.md#static-file-server) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily. - [**Ungit**](./features.md#ungit) - rings user friendliness to git without sacrificing the versatility of it. - [**MkDocs**](./docs.md) - create documentation for your workspace or project with only markdown. - [**Midnight Commander**](https://midnight-commander.org/) - Feature rich visual file manager with internal text viewer and editor. - [**Process Monitor**](https://htop.dev/) - Monitor running process and resource utilization. Base-Workspace has 3 text editors installed: [Nano](https://www.nano-editor.org/), [Vim](https://www.vim.org/), [McEdit](https://linux.die.net/man/1/mcedit). Vim is more powerful, but has steeper learning curve. If you haven't used it, I'd recommend Nano or McEdit. ## Launch Workspace In order to avoid confusion, the following convention is adopted: ```sh command to execute outside of the workspace (outer environment) ``` > `command to execute in the workspace terminal (inside workspace)` To start Base-Workspace simply execute in terminal ```sh docker run --name space-1 -d -p 8020-8030:8020-8030 alnoda/base-workspace ``` The default workspace user is *abc* with passwordless sudo only to install packages. This is a reasonable balance between security and flexibility, and in most cases a workspace should run under the default *abc* user, even it is used internally. There are some limitations for *abc* user. For example, despite bein able to install applications with *sudo apt-get* users will not be able to install with *Snap* (at least currently). Non-root user is also not able to use docker-in-docker, otherwise she will get access to the entire docker on the host server. If it is required to run the workspace entirely under a *root* user, run it with "--user=root" ```sh docker run --name space-1 --user=root -d -p 8020-8030:8020-8030 alnoda/base-workspace ``` **NOTE:** even if workspace is running under non-root user, you can always ssh into it as root user (but not from the browser-based terminal). ### Workspace terminal There are 2 ways how to work with the terminal of the Base-Workspace. The easiest way is to use browser-based termnal. It is a full-featured complete terminal. Launch it from the Base-Workspace UI
Browser-based terminal always uses the user you started workspace with (default is non root user *abc*). Another way to work with the wordkspace terminal - is to ssh into the running docker container from the terminal of the outer environment. Same way we ssh into any docker container ```sh docker exec -it space-1 /bin/zsh ``` and, if you don't want to use z-shell ``` docker exec -it space-1 /bin/bash ``` This way allows to ssh into the workspace as a *root* user at any time, even if the workspace itself was not starter as root user (the default user is *abc*) ```sh docker exec -it --user=root space-1 /bin/zsh ``` ### Multiple workspaces Every workspace requires range of ports. If one workspace is up and running, the ports 8020-8030 are taken. In order to start another workspace, you either need to stop currently runnning workspace, or to run another workspace on the different port range. If you are planning to run more than one workspace at the same time, you can run another workspace with the different port range, for example ```sh docker run --name space-2 -d -p 8040-8050:8020-8030 -e ENTRY_PORT=8040 alnoda/base-workspace ``` Notice that in addition we need to set environmental variable ENTRY_PORT, which should be equal to the first port in the new range. Workspace UI usues this variable to know the new port range, and redirects to the proper addresses of the workspace applications' UIs. ### Open more ports We started workspace container with a port range mapped "-p 8020-8030". If you are planning to expose more applications from inside of a container, add additional port mapping, for example ```sh docker run --name space-1 -d -p 8020-8030:8020-8030 -p 8080:8080 alnoda/base-workspace ``` You can add multiple port mappings: ```sh docker run --name space-1 -d -p 8020-8030:8020-8030 -p 8080:8080 -p 443:443 alnoda/base-workspace ``` **NOTE:** It is not a problem if you don't expose any ports, but later on realise you need them - you will just create new image, and run it exposing the required port (look in the section [Create new image](#create-new-image)) ### Docker in docker It is possible to work with docker directly from the workspace (using workspace terminal). ``` docker run --name space-1 -d -p 8020-8030:8020-8030 -v /var/run/docker.sock:/var/run/docker.sock alnoda/base-workspace ``` NOTE: in order to use docker in docker you need to or enter into the workspace container as root ```sh docker exec -it --user=root space-1 /bin/zsh ``` ### Run on remote server Because workspace is just a docker image, running it in any other server is as easy as running it on local laptop. Running on remote server makes it much simpler to collaborate, because you can just share credentials to the workspace with your peers, and they will be able to use it. You can also run applications that should run permanently, and run jobs on schedule. The simplest deployment of the workkspace requires only 3 steps: - get virtual server on your favourite cloud (Digital Ocean, Linode, AWS, GC, Azure ...) - [install docker](https://docs.docker.com/engine/install/) on this server - ssh to the remote server and start workspace ``` docker run --name space-1 -d -p 8020-8030:8020-8030 -e WRK_HOST="