CodeMirror/alnoda-workspaces
1
0
Fork 0
mirror of https://github.com/bluxmit/alnoda-workspaces.git synced 2024-06-26 18:20:24 +12:00
Code Issues Projects Releases Wiki Activity

updated workspaces: base,ide,codeserver

Browse source
This commit is contained in:
bluxmit 2022-05-09 18:48:16 +00:00
parent 00ce360e08
commit 5c763370d8
24 changed files with 748 additions and 1837 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
workspaces/ansible-terraform-workspace/README.md
View file

@ -45,7 +45,7 @@ and open [localhost:8020](http://localhost:8020) in browser.
- [**Inframap**](https://github.com/cycloidio/inframap)
## Docs
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](docs/features.md).
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](../ubuntu-workspace/docs/workspaces.md).
<div align="center" style="font-style: italic;">
Demo: Ansible-Terraform workspace

635
workspaces/ansible-terraform-workspace/docs/features.md
View file

@ -1,635 +0,0 @@
# ansible-Terraform workspace advanced features
## Contents
* [Full list of features ](#full-list-of-features )
* [Use-cases](#use-cases)
* [Launch Workspace](#launch-workspace)
* [Start local workspace](#start-local-workspace)
* [Understanding ports](#understanding-ports)
* [Workspace terminal](#workspace-terminal)
* [Multiple workspaces](#multiple-workspaces)
* [Run on remote server](#run-on-remote-server)
* [Unsecure remote workspace](#unsecure-remote-workspace)
* [Secure remote workspace](#secure-remote-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)
* [Save workspace as a file](#save-workspace-as-a-file)
* [Push workspace to a docker registry](#push-workspace-to-a-docker-registry)
* [Move workspace to the cloud](#move-workspace-to-the-cloud)
* [Workspace environment](#workspace-environment)
* [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)
* [Workspace Documentation](#workspace-documentation)
## Full list of features
**Ansible tools:**
- [**Ansible Ara**](https://github.com/ansible-community/ara)
- [**Ansible-cmdb**](https://github.com/fboender/ansible-cmdb)
- [**Ansible inventory grapher**](https://github.com/willthames/ansible-inventory-grapher)
- [**Ansible Playbook Grapher**](https://github.com/haidaraM/ansible-playbook-grapher)
- [**Ansible Lint**](https://ansible-lint.readthedocs.io/en/latest/installing.html)
- [**Ansible Doctor**](https://ansible-doctor.geekdocs.de/)
**Terraform tools:**
- [**Pre-commit-terraform**](https://github.com/antonbabenko/pre-commit-terraform)
- [**Rover**](https://github.com/im2nguyen/rover)
- [**Blast-Radius**](https://github.com/28mm/blast-radius)
- [**Terraform Visual**](https://github.com/hieven/terraform-visual)
- [**Terraform Graph**](https://www.terraform.io/docs/cli/commands/graph.html)
- [**Inframap**](https://github.com/cycloidio/inframap)
**Workspace tools with UI:**
- **Workspace UI** - Browser-based UI for Ansible-Terraform Workspace. Launch all workspace tools from one place. Customize to your yown needs.
- [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has
VS-Code extensions and works in browser. This means it can run inside a docker container on local machine or in cloud. For the Ansible-Terraform workspace beautiful [SynthWave '84](https://open-vsx.org/extension/RobbOwen/synthwave-vscode) theme is set by default.
- [**Terminal**](https://github.com/tsl0922/ttyd) - secure browser-based terminal.
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- [**Cronicle**](https://github.com/jhuckaby/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**](https://github.com/vercel/serve) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
- [**Ungit**](https://github.com/FredrikNoren/ungit) - rings user friendliness to git without sacrificing the versatility of it.
- [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) - maintain 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.
**Common:**
- Ubuntu 20.4
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow, lazygit
- curl, wget, telnet, jq
- nano, vim, mc
- ncdu, htop, glances, vizex
- supervisord
- cron
By default workspace runs under user **abc** - a secure non-root user, abile to install new packages with apt-get, pip, npm. Workspace
can be launched as root user too, but it is less secure, and not recommended if provided as a service for other users.
## Use-cases
There are several reasons to use this workspace.
1) Convenience. Get started fast, without wasting time on setting all those tools yourself.
Getting Ansible and Terraform ready to be used, is as simple as starting a docker container. In addition, you get the ability to start and stop multiple workspaces, this makes managing separate independent cloud infrastructures much easier and safe,
for example, you don't need to switch AWS profiles all the time. Also, you can export the entire workspace to file, push to a (private) Docker registry, and keep different versions of the workspace.
2) Deploy the workspace on a cloud server. Schedule ansible playbooks with Cronicle and observe ansible executions with Ara dashboard.
Deployment of this workspace on a cloud server is very handy when you need security, and most of your infra is running in a private network.
The latter makes it impossible to use a local machine as an executor for Ansible playbooks unless you set up a complex VPN. This workspace can
be launched on a bridge server that is in both private and public networks, and you can use browser-based tools to develop and execute
Ansible or Terraform code. Here it is explained how to launch Ansible-Terraform Workspace on a cloud server with HTTPS and authentication.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/infra-wrk-network.png" alt="Htop" width="750">
</p>
3) Reduce the risk of conflicting executions. Despite there are ways to prevent conflicting executions of Ansible playbooks or
applying Terraform code (i.e. remote Terraform state), this Workspace makes it even easier, when it is deployed on the remote
cloud server, and used by multiple users.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/collaborate.png" alt="Htop" width="750">
</p>
*(you need to implement lock file in Ansible yourself, it is not a standard feature of Ansible.)*
#### Why using workspace
In addition to what's already mentioned, Ansible-Terraform Workspace has the benefits of any other dockerized workspace:
- Avoid the tedious process of setting dev environment on your laptop
- Work conveniently with multiple IT projects on the same laptop
- Move all your work to another machine easily
- Start working right away in the workspace prepared for the task
- Run dev environment in cloud and work from any device, be independent on any cloud service or cloud provider
- Back-up entire workspaces with important work, save versions of the workspaces before changes
- Collaborate by sharing the entire workspace or run it in the cloud
- Move from dev to POC/MVP in a minute
- Make experiments (try new packages, versions, frameworks) without risking affecting existing environment
- With a single command start, stop and resume job schedules, related to the same project
- Create a custom dev environment for your team, and help new-comers to save time on setting up their environments
- Move dev environment back and forth between powerful Windows PC and macOS laptop in minutes
Read in detail about the [advantages of the dockerized workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/README.md#why-workspace-in-docker)
and the [situations when workspace is a good choice](https://github.com/bluxmit/alnoda-workspaces/blob/main/README.md#use-cases)
## Launch Workspace
### Start local workspace
Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands,
no need to learn any new tools.
In order to avoid confusion, the following convention is adopted:
```sh
command to execute outside of the workspace
```
> `command to execute inside the workspace (after entering running docker container)`
To start a workspace simply execute in terminal
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 9000:9000 alnoda/ansible-terraform-workspace
```
*(It is recommended to run workspace in the daemon mode)*
***Open [http://localhost:8020](http://localhost:8020)***
Workspace has its own UI, which includes quiklaunch (home) page and documentation pages.
From the quiklaunch you can open any workspace tool. Documentation pages you modify in order
to document the project, workspace use and setup.
### Understanding ports
In a previous section workspace was started with a port range mapping ***-p 8020-8035***.
This is because workspace contains a set of applications with browser-based UI
| Port | Application |
| --------- | ------------------------- |
| 8020 | Workspace UI |
| 8021 | Filebrowser |
| 8022 | Static file server |
| 8023 | Cronicle |
| 8024 | Ungit |
| 8025 | VS-Code (Theia) |
| 8026 | Terminal |
| 8027 | Midnight Commander |
| 8028 | Htop |
| 8029 | Ansible Ara |
You don't need to memorize these ports. Ansible-Terraform workspace has UI from where you can open any of these applications.
Open [localhost:8020](http://localhost:8020), and from there open other applications included in the workspace.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/Workspace%20UI.png" alt="Htop" width="750">
</p>
The rest of the ports from the port range can be used in order to expose optional applications, or applications you might
install in future. So we map several extra ports just inn case.
Ansible-Terraform workspace has the following applications installed, but not started by default
1) **Terraform Rover** provides great visualization for your Terraform infrastructure. To visualize any (initialized) Teffarorm project
execute
> `rover --workingDir <TERRAFORM_PROJECT_FOLDER>`
For example, `rover --workingDir /home/examples/terraform-scaleway/`
**NOTE:** Terraform Rover only runs on the internal port 9000, that's why when running Ansible-Terraform workspace
it is necessary to map this port explicitly.
2) **Terraform Blast-Radius** - a tool for reasoning about Terraform dependency graphs with interactive visualizations.
Start Blast-Radius on any of the free port in the mapped range:
> `cd /home/examples/terraform-scaleway && terraform init && blast-radius --serve --port 8030`
If you are planning to expose more applications
from inside of a container, add additional port mapping, for example
Of course, you can add even more port mappings to your workspace, for example:
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 9000:9000 -p 8080:8080 -p 443:443 alnoda/ansible-terraform-workspace
```
**NOTE:** It is not a problem if you don't expose any ports from the first run. You can expose the required ports by [creating new image](#create-new-image).
### Multiple workspaces
Typically you would run one workspace at a time, but there might be cases when launching more than one workspace might be needed.
Every workspace needs a range of ports. If one workspace is up and running, and uses the default port range, then ports 8020-8035 are taken.
Ansible-terraform workspace itself uses 10 ports (8020-8029), but it is recommended to map several extra ports for the applications you
will launch when working in the workspace, for example, Blast Radius or Rover. Having extra ports,
you can always launch new applications on these ports, and they will be immediately exposed outside of the workspace.
In order to start another workspace we need to provide a different port range, for example
```sh
docker run --name space-2 -d -p 8040-8055:8020-8035 -e ENTRY_PORT=8040 alnoda/ansible-terraform-workspace
```
Notice that in addition we set environmental variable ***ENTRY_PORT***, which should be equal to the first port in the new range.
Environmental variable ENTRY_PORT tells workspace that non-default port range is used, for Workspace UI to open applications
on proper ports in browser.
### Workspace terminal
Terminnal - is one of the main developer tools. There are several ways how to work with terminal of the the ansible-terraform workspace:
- built-it in-browser terminal
- use terminal provided by in-browser IDE [http://localhost:8025](http://localhost:8025) ([unless other ports are mapped](#multiple-workspaces))
- ssh into the running the docker container (of the workspace) from your terminal
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/terminal.gif" alt="Base-Workspace terminal" width="500">
</p>
*(Browser-based terminals always work under the user you started the workspace with, the default is non root user "abc")*
If you want to enter running workspace container from your terminal execute:
```sh
docker exec -it space-1 /bin/zsh
```
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
```
You can work in the Ubuntu terminal now. Execute the following command to know your workspace user
> `whoami`
### 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.
#### Unsecure remote workspace
The simplest deployment of the workspace 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-8035:8020-8035 -p 9000:9000 -e WRK_HOST="<ip-of-your-remote-server>" alnoda/ansible-terraform-workspace
```
**NOTE:** When running workspace on the remote server, add envronmental variable `-e WRK_HOST="<ip-of-your-remote-server>"`.
Workspace UI needs this variable to know how redirect properly to the workspace applications' UIs.
Open in your browser `<ip-of-your-remote-server>:8020`
If docker-in-docker is required, then
```
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 9000:9000 -e WRK_HOST="<ip-of-your-remote-server>" -v /var/run/docker.sock:/var/run/docker.sock alnoda/ansible-terraform-workspace
```
This way launches workspace in cloud, but such workspace would not be secure, everyone who knows IP of your server will be able to use it. You should
use this method only if you launch workspace in the secure internal network or inside a VPN.
#### Secure remote workspace
*You might want to restrict access to the cloud workspace, and secure encrypted communication with it*
There are many situations when running Ansible-Terraform workspace in the public network over Internet is required. This can be done
by running the Workspace behind the reverse proxy over secure encrypted HTTPS protocol with authentication. [Here](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/ansible-terraform-workspace/docs/example-compose.md) is the example of a
docker-compose file that launches Ansible-Terrafom workspace behind the proxy with middlewares that enable HTTPS and auth (TLS certificates are
not included in the example). For some engineers it might be an easy task to make such a thing, but for many who do not have experience in this area,
this would be a daunting task that can easily consume several days of your life. That's why Ansible-Terraform workspace comes with a nice little tool, that generates a docker-compose project
(including certificates and passwords) to easily, securely and without hassle launch workspace on any cloud server
***Ansible-terraform-workspace contains utility that will generate everything needed to launch the workspace in cloud in a secure way, with authentication and with TLS.***
If you would like to run workspace on the remote server securely, launch ansible-terraform workspace on your local laptop first, open its terminal and
use utility `/home/abc/utils/remote.py` to generate create docker-compose project with TLS certificates. Simply execute
> `python /home/abc/utils/remote.py --workspace="ansible-terraform-workspace" --port="<ENTRY_PORT>" --host="<IP_OF_CLOUD_SERVER_WITH_PUBLIC_ACCESS>" --user="<ANY_USER_NAME>" --password="<ANY_USER_PASSWORD>"`
for example:
> `python /home/abc/utils/remote.py --workspace="ansible-terraform-workspace" --port="8020" --host="68.183.69.198" --user="user1" --password="pass1"`
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
After the command is executed, you will see folder `/home/abc/utils/remote` is created. Download it out from the workspace to the local environment using the Filebrowser:
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/generate-remote.gif" alt="Htop" width="900">
</p>
Copy this folder to the remote server where you want to launch Ansible-Terraform workspace.
You can use cyberduck or [scp](https://kb.iu.edu/d/agye). ssh to the server, cd to the directory you copied and execute
```sh
docker-compose up -d
```
That's it, your workspace is running securely on the remote server, using
self-signed TLS certificates for encrypted HTTPS communication between your laptop and the remote workspace, and authentication is added.
## Manage workspaces
Workspace is just a docker container. You can start, stop, delete and do anything you can do with docker images and containers.
There are two concepts to keep in mind: **images** and **containers**. Images are workspace blueprints. For example, **alnoda/ansible-terraform-workspace** -
is an image. When you execute this command
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 9000:9000 alnoda/ansible-terraform-workspace
```
you create container called **space-1** from the image **alnoda/ansible-terraform-workspace**. You can create any number of containers, but you need to
[map different ports to each of them](#multiple-workspaces).
Container - is your workspace. You can start, stop and delete them. You can run multiple workspace containers at the same time, or work with
one workspace at a time.
From the workspace (which is a container) you can create new image. This is called **commit docker image**.
Essentially, this means *"take my workspace and create new image with all the changes I've done in my workspace*"
### Start and stop workspaces
The workspace started in daemon mode will continue working in the background.
See all the running docker containers
```
docker ps
```
Stop workspace
```sh
docker stop space-1
```
Workspace is stopped. All the processes and cron jobs are not running.
See all docker containers, including stopped
```
docker ps -a
```
Start workspace again. Processes and cron jobs are resumed.
```sh
docker start space-1
```
Delete workspace container (all work will be lost)
```
docker rm space-1
```
### Create new workspace image
Having made changes, you can commit them creating new image of the workspace. In order to create new workspace image with the
name "space-image" and version "0.2" execute
```
docker commit space-1 space-image:0.2
```
Run new workspace with
```
docker run --name space2 -d space-image:0.2
```
The new workspace accommodates all the changes that you've made in your space-1. Hence you can have versions of your workspaces.
Create different versions before the important changes.
### Manage workspace images
See all docker images
```
docker images
```
Delete workspace image entirely
```
docker rmi -f alnoda/ansible-terraform-workspace
```
**NOTE:** you cannot delete image if there is a running container created from it. Stop container first.
### Save and load workspace images
After you commit workspace container, and create new image out of it, you can push it to your docker registry or save it in a file.
#### Save workspace as a file
Assuming you created new image **space-image:0.4** from your workspace, you can save it as a tar file
```
docker save space-image:0.4 > space-image-0.4.tar
```
We can delete the image with
```
docker rmi -f space-image:0.4
```
And restore it from the tar file
```
docker load < space-image-0.4.tar
```
#### Push workspace to a docker registry
A better way to manage images is docker registries. You can use docker registries in multiple clouds. They are cheap and very convenient.
Check out for example, [Registry in DigitalOcean](https://www.digitalocean.com/products/container-registry/) or in [Scaleway container registry](https://www.scaleway.com/en/container-registry/). There are more.
Pushing image to registry is merely 2 extra commands: 1) tag image; 2) push image
You will be able to pull image on any device, local or cloud.
### Move workspace to the cloud
Ease of running workspace in cloud, and ability to move workspaces between local machine and remote server -
is one of the main features of the workspace, and the reason why the workspace is entirely in docker.
It is often a case that experiment, which started on personal notebook require more computational
resources, must be running for a long period of time, or executed periodically. All of these cases are
the reasons to move a workspace to the cloud server. Usually it is a hassle, but this workspace can be moved
to the remote server easily.
The easiest way to move workspace to the cloud is to get your private docker registry. Then moving a workspace from a laptop to
a remote server is only 3 commands:
1. [Commit workspace to the a image](#create-new-workspace-image)
2. [Push workspace to your docker registry](https://docs.docker.com/engine/reference/commandline/push/)
3. ssh to remote server, and [run workspace there](#run-on-remote-server)
If you don't want to use container registry, then there are 2 steps more involved:
1. [Commit workspace to the a image](#create-new-workspace-image)
2. [Save image to file](#save-workspace-as-a-file)
3. Copy file to remote server. There are many options:
- Launch filexchange workspace on the remote server
- Use [cyberduck](https://cyberduck.io/)
- use [scp](https://linuxize.com/post/how-to-use-scp-command-to-securely-transfer-files/)
4. [Load workspace image from file](#save-and-load-workspace-images) on the remote server
5. [Start workspace on the remote server](#run-on-remote-server)
## Workspace environment
Workspace is based on the Ubuntu 20.04 docker image.
### Common workspace actions
Common actions you'd do in the workspace
- installation of new applications and runtimes
- edit files, write code, scripts
- build, compile and execute code
- start/stop applications and services
- schedule tasks and scripts
- process data
#### Install applications
Use workspace workspace terminal to install new applications.
Install with ```sudo apt install```. The default *abc* user is allowed to install packages.
For example, in order to install [Emacs text editor](https://www.gnu.org/software/emacs/) open workspace terminal, and execute
> `sudo apt install emacs`
#### Schedule jobs with Cron
Schedule execution of any task with cron - a time-based job scheduler in Unix-like computer operating systems.
Open workspace terminal, and execute
> `crontab -e`
*(chose [1] nano as editor on the first time)*
In the end of the opened file add line
> `* * * * * echo $(whoami) >> /home/cron.txt`
This will print every minute username to file */home/cron.txt* . *(Hit Ctrl+X to exit nano)*
Hint: example of cron job definition:
```
.---------------- minute (0 - 59)
| .------------- hour (0 - 23)
| | .---------- day of month (1 - 31)
| | | .------- month (1 - 12) OR jan,feb,mar,apr ...
| | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
| | | | |
* * * * * command to be executed
```
**NOTE** you can disconnect from the image and close terminal - cron will continue working.
> Instead of cron you might want to use Cronicle - a tool with Web UI, and a great list of features
> that will provide you with the dashboard, list of executions and statistics, even let you set limits
> on resources for each jobs, and create dependencies between jobs.
#### Python
Python and Pip are installed. To use python console, open workspace terminal and execute
> `python`
install python package with pip, for
> `pip install pandas`
If you are planning to work with python, we recommend to install IPython, that provides a rich toolkit to help
you make the most of using Python interactively. Install and start ipython
> ```pip install ipython```
> `ipython`
#### Node.js
We recommend to use nodeenv to create different node environments.
For example, open workspace terminal, create folder npmgui, and activate environment with node v. 12.18.3 and npm v.6.0.0
> `cd /home`
> `mkdir npmgui; cd npmgui`
> `nodeenv --node=12.18.3 --npm=6.0.0 env`
Let's install package and start node application
> `. env/bin/activate && npm i -g npm-gui`
> `npm-gui 0.0.0.0:8030`
Open your browser on http://localhost:8030/
**NOTE:** If you close terminal, the application will stop. See how to [start applications that reamin live after closing a workspace terminal](#run-applications-and-services-inside-the-workspace)
#### Run applications and services inside the workspace
If you want application to keep running after workspace terminal is closed start it with **"&!"** at the end.
For example, in the last section we started *npm-gui* tool with command `npm-gui 0.0.0.0:8030`. If you close the workspace terminal,
this application will stop running. To keep it running after terminal is closed, execute
> `npm-gui 0.0.0.0:8030 &!`
Now, if you disconnect from the workspace and close terminal, the application will continue running in the workspace, untill [workspace is stopped](#start-and-stop-workspaces).
## Workspace Documentation
Workspace can easily be customized for your specific needs. You can also use Workspace for a complex project, and might need a
tool to write remarks, plans, action plans. As well as architectural artifacts for the components you wish to implement. Often it is
also needed to store somewhere snippets of code or shell commands that you often use in your work. It would be uncomfortable to use extra
tool or solution outside of the Workspace to store such remarks.
Because Workspace is a complete self-contained environment, it include tools to make remarks, plans, store pieces of code, write anything,
and even build complete static documentation websites that you can host on GitHub Pages for example.
[MkDocs](https://www.mkdocs.org/) is a part of the workspace, and its dev server is up and running every time you start the Workspace. In fact,
the workspace UI (port 8020 by default) - is served by the MkDocs dev server.
You can easily modify the UI, add more pages or update existing pages. The changes will be updated immediately without the need to do anything.
MkDocs project is located in the `/home/docs/` folder. It has subfolder called `docs` (so it is `/home/docs/docs/`) where all the Markdown documents
are stored. Simply create new `.md` file there. And add reference about this file to the MkDocs config `/home/docs/mkdocs.yml`. You will see that
the new page has appeared in your Workspace UI - it has live reload, and you don't need to do anything, just write in the markdown files.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/workspace-docs.gif" alt="workspace-docs" width="900">
</p>
You can easily build beautiful static website from this documentation
> `cd /home/docs/ && mkdocs build -d /home/static-server/my-doc-website`
The resulting HTML website is in folder `/home/static-server/my-doc-website`, you can view it with Static File Server and download to local
with Filebrowser
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/workspace-docs-build.gif" alt="workspace-docs-build" width="900">
</p>
You can make even more stunning documentation websites with advanced Markdown features using [MkDocs-Magicspace](https://mkdocs-magicspace.alnoda.org/).

17
workspaces/ansible-terraform-workspace/docs/getting-started.md
View file

@ -1,7 +1,5 @@
# Getting started
## General
### Quicklaunch
From the quicklaunch page you can open workspace tools, such as code editor or terminal
@ -20,14 +18,6 @@ Code editor of this workspace is [**Eclipse Theia**](https://theia-ide.org/docs/
despite Eclipse Theia is a browser-based code editor, it is fast, responsive, and full-featured. It features code highlighting, autocompletion,
rendering of notebooks has a tree-based file browser, and a great number of pre-installed color themes.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/theia-themes.png" alt="theia-themes.png" width="900">
</p>
You can install any extension from [open-vsx.org](https://open-vsx.org/) that has hundreeds of extensions for VS Code compatible editors.
The IDE is already configured to make code highlighting for a great number of programming languages and file types. It also has many
popular extensions installed
<div align="center" style="font-style: italic;">
Demo: Eclipse Theia
</div>
@ -36,6 +26,11 @@ popular extensions installed
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/theia.gif" alt="Theia demo" width="900">
</p>
You can install any extension from [open-vsx.org](https://open-vsx.org/) that has hundreeds of extensions for VS Code compatible editors.
The IDE is already configured to make code highlighting for a great number of programming languages and file types. It also has many
popular extensions installed
### Terminal
Workspace has full-size browser-base terminal
@ -208,7 +203,7 @@ can use to view the artifacts, that include interactive HTML pages
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/terraform-report-scaleway.gif" alt="Htop" width="500">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/terraform-report-scaleway.gif" alt="Htop" width="750">
</p>

2
workspaces/base-workspace/Dockerfile
View file

@ -20,7 +20,7 @@ COPY supervisord-workspace-base.conf /etc/supervisord/
COPY filebrowser.json /opt/filebrowser/.filebrowser.json
COPY mkdocs /home/docs
COPY README.md /home/docs/docs/docs.md
COPY docs/getting-started.md /home/docs/docs/getting-started.md
COPY mkdocs-requirements.txt /home/abc/installed-python-packages/mkdocs-requirements.txt
RUN echo "------------------------------------------------------ filebrowser, ungit, static server" \

500
workspaces/base-workspace/README.md
View file

@ -1,502 +1,54 @@
<p align="center">
<img src="https://github.com/bluxmit/alnoda-workspaces/blob/main/img/Alnoda-white.svg" alt="Alnoda logo" width="150">
</p>
</p>
# Base-workspace
Containerized Linux environment for running jobs on schedule with browser-based scheduler, terminal and file manager.
You can host on your favourite Rasberry Pi.
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.
Start
#### 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.
and open [localhost:8020](http://localhost:8020) in 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.
- Quicklaunch UI with getting started tutorial
- **Ubuntu 20.4** with the following apps
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow, lazygit
- curl, wget, telnet, jq
- nano, vim, mc
- ncdu, htop, glances, vizex
- supervisord
- cron
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.
## Why this image
## Launch Workspace
If you need to schedule scripts and jobs, monitor executions, upload and download files.
In order to avoid confusion, the following convention is adopted:
## Docs
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](../ubuntu-workspace/docs/workspaces.md).
```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
<div align="center" style="font-style: italic;">
Demo: Base workspace
</div>
<p align="center">
<img src="./img/base-workspace-terminal.gif" alt="Base-Workspace terminal" width="500">
</p>
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 (often you can get server with docker already installed)
- ssh to the remote server and start workspace
```
docker run --name space-1 -d -p 8020-8030:8020-8030 -e WRK_HOST="<ip-of-your-remote-server>" alnoda/base-workspace
```
**NOTE:** When running workspace on the remote server, add envronmental variable `-e WRK_HOST="<ip-of-your-remote-server>"`.
Workspace UI needss this variable to know how redirect properly to the workspace applications' UIs.
Open in your browser `<ip-of-your-remote-server>:8020`
If docker-in-docker is required, then
```
docker run --name space-1 -d -p 8020-8030:8020-8030 -e WRK_HOST="<ip-of-your-remote-server>" -v /var/run/docker.sock:/var/run/docker.sock alnoda/base-workspace
```
This way launches workspace in cloud, but such workspace is not secure, everyone who knows IP of your server will be able to use it.
***You might want to restrict access to the workspace, and secure encrypted communication with the workspace***
Base-Workspace contains utility that will generate everything needed to launch the workspace in cloud.
If you want to run workspace on the remote server securely, start Base-Workspace on your local laptop first, open its terminal and
use utility `/home/abc/utils/remote.py` to generate create docker-compose project with TLS certificates. Simply execute
> `python /home/abc/utils/remote.py --workspace="base-workspace" --port="8020" --host="68.183.69.198" --user="user1" --password="pass1"`
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
You see folder `/home/abc/utils/remote` is created. Copy this folder to the remote server (any location). Ssh to the server, cd into
the directory you copied and execute `docker-compose up -d`.
That's it, you workspace is running securely on the remote server, using
self-signed TLS certificates for encrypted https communication between you laptop and the remote workspace,
and authentication is added.
## Use Workspace
Among the common actions you'd do in the workspace are
- installation of new applications and runtimes
- edit files, write code, scripts
- build, compile and execute code
- start/stop applications and services
- schedule tasks and scripts
- process data
### Install applications
Use workspace workspace terminal to install new applications.
Install with ```sudo apt install```. The default *abc* user is allowed to install packages.
For example, in order to install [Emacs text editor](https://www.gnu.org/software/emacs/) open workspace terminal, and execute
> `sudo apt install emacs`
### Schedule jobs with Cron
Schedule execution of any task with cron - a time-based job scheduler in Unix-like computer operating systems.
Open workspace terminal, and execute
> `crontab -e`
*(chose [1] nano as editor on the first time)*
In the end of the opened file add line
> `* * * * * echo $(whoami) >> /home/cron.txt`
This will print every minute username to file */home/cron.txt* . *(Hit Ctrl+X to exit nano)*
Hint: example of cron job definition:
```
.---------------- minute (0 - 59)
| .------------- hour (0 - 23)
| | .---------- day of month (1 - 31)
| | | .------- month (1 - 12) OR jan,feb,mar,apr ...
| | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
| | | | |
* * * * * command to be executed
```
**NOTE** you can disconnect from the image and close terminal - cron will continue working.
> Instead of cron you might want to use Cronicle - a tool with Web UI, and a great list of features
> that will provide you with the dashboard, list of executions and statistics, even let you ser limis
> on resources for each jobs, and create depenndencies between jobs.
### Python
Python and Pip are installed. To use python console, open workspace terminal and execute
> `python`
install python package with pip, for
> `pip install pandas`
If you are planning to work with python, we recommend to install IPython, that provides a rich toolkit to help
you make the most of using Python interactively. Install and start ipython
> ```pip install ipython```
> `ipython`
### Node.js
We recommend to use nodeenv to create different node environments.
For example, open workspace terminal, create folder npmgui, and activate environment with node v. 12.18.3 and npm v.6.0.0
> `cd /home`
> `mkdir npmgui; cd npmgui`
> `nodeenv --node=12.18.3 --npm=6.0.0 env`
Let's install package and start node application
> `. env/bin/activate && npm i -g npm-gui`
> `npm-gui 0.0.0.0:8030`
Open your browser on http://localhost:8030/
**NOTE:** If you close terminal, the application will stop. See how to [start applications that reamin live after closing a workspace terminal](#run-applications-and-services-inside-the-workspace)
### Run applications and services inside the workspace
If you want application to keep running after workspace terminal is closed start it with **"&!"** at the end.
For example, in the last section we started *npm-gui* tool with command `npm-gui 0.0.0.0:8030`. If you close the workspace terminal,
this application witll stop running. To keep it running after terminal is closed, execute
> `npm-gui 0.0.0.0:8030 &!`
Now, if you disconnect from the workspace and close terminal, the application will continue running in the workspace, untill [workspace is stopped](#start-and-stop-workspaces).
## Manage workspaces
Workspace is just a docker container. You can start, stop, delete and do anything you can do with docker images and containers.
There are two concepts to keep in mind: **images** and **containers**. Images are workspace blueprints. For example, **alnoda/base-workspace** -
is an image. When you execute this command
```sh
docker run --name space-1 -d -p 8020-8030:8020-8030 alnoda/base-workspace
```
you create container called **space-1** from the image **alnoda/base-workspace**. You can create any number of containers, but you need to
[map different ports to each of them](#multiple-workspaces).
Container - is your workspace. You can start, stop and delete them. You can run multiple workspace containers at the same time, or work with
one workspace at a time.
From the workspace (which is a container) you can create new image. This is called **commit docker image**.
Essentially, this means *"take my workspace and create new image with all the changes I've done in my workspace*"
### Start and stop workspaces
The workspace started in daemon mode will continue working in the background.
See all the running docker containers
```
docker ps
```
Stop workspace
```sh
docker stop space-1
```
Workspace is stopped. All the processes and cron jobs are not running.
See all docker conntainers, including stopped
```
docker ps -a
```
Start workspace again. Processes and cron jobs are resumed.
```sh
docker start space-1
```
Delete workspace container (all work will be lost)
```
docker rm space-1
```
### Create new workspace image
Having made changes, you can commit them creating new image of the workspace. In order to create new workspace image with the
name "space-image" and version "0.2" execute
```
docker commit space-1 space-image:0.2
```
Run new workspace with
```
docker run --name space2 -d space-image:0.2
```
The new workspace accommodates all the changes that you've made in your space-1. Hence you can have versions of your workspaces.
Create different versions before the important changes.
### Manage workspace images
See all docker images
```
docker images
```
Delete workspace image entirely
```
docker rmi -f alnoda/base-workspace
```
**NOTE:** you cannot delete image if there is a running container created from it. Stop container first.
### Save and load workspace images
After you commit workspace container, and create new image out of it, you can push it to your docker registry or save it in a file.
#### Save workspace in a file
Assuming you created new image **space-image:0.4** from your workspace, you can save it as a tar file
```
docker save space-image:0.4 > space-image-0.4.tar
```
We can delete the image with
```
docker rmi -f space-image:0.4
```
And restore it from the tar file
```
docker load < space-image-0.4.tar
```
#### Push workspace to a registry
A better way to manage images is docker registries. You can use docker registries in multiple clouds. They are cheap annd very convenient.
Check out for example, [Registry in DigitalOcean](https://www.digitalocean.com/products/container-registry/) or in [Scaleway container registry](https://www.scaleway.com/en/container-registry/). There are more.
Pushing image to registry is merely 2 extra commands: 1) tag image; 2) push image
You will be able to pull image on any device, local or cloud.
### Move workspace to the cloud
Ease of running workspace in cloud, and ability to move workspaces between local machine and remote server -
is one of the main features of the workspace, and the reasonn why the workspace is entirely in docker.
It is often a case that experiment, which started on personal notebook require more computational
resources, must be running for a long period of time, or executed periodically. All of these cases are
the reasons to move a workspace to the cloud server. Usually it is a hassle, but this workspace can be moved
to the remote server easily.
The easiest way to move workspace to the cloud is to get your private docker registry. Then moving a workspace from a laptop to
a remote server is only 3 commands:
1. [Commit workspace to the a image](#create-new-workspace-image)
2. [Push workspace to your docker registry](https://docs.docker.com/engine/reference/commandline/push/)
3. ssh to remote server, and [run workspace there](#run-on-remote-server)
If you don't want to use container registry, then there are 2 steps more involved:
1. [Commit workspace to the a image](#create-new-workspace-image)
2. [Save image to file](save-and-loa-images)
3. Copy file to remote server. There are many options:
- Launch filexchange workspace on the remote server
- Use [cyberduck](https://cyberduck.io/)
- use [scp](https://linuxize.com/post/how-to-use-scp-command-to-securely-transfer-files/)
4. [Load workspace image from file](#save-and-load-workspace-images) on the remote server
5. [Start workspace on the remote server](#run-on-remote-server)
<img src="https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/img/base-workspace.gif" alt="Base Workspace" width="750">
</p>

0
workspaces/base-workspace/doc/future-improvements.md → workspaces/base-workspace/docs/future-improvements.md
View file

55
workspaces/base-workspace/docs/getting-started.md Normal file
View file

@ -0,0 +1,55 @@
# Get started
This tutorial shows how to scrap Google news on schedule with Base Workspace.
Navigate to Quickstart and open Terminal
<p align="center">
<img src="https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/img/base-workspace-terminal.gif" alt="Terminal" width="500">
</p>
Install Python package GNews
```
pip install gnews
```
Create python script file, and start editing
```
nano scraper.py
```
Paste the following code snippet. This is scrapper, that will output results to a file
```py
from gnews import GNews
import json
google_news = GNews()
usa_news = google_news.get_news('USA')
with open('usa_news.json', 'w') as f:
json.dump(usa_news, f)
```
Save the file with `Ctrl+s` and return to the terminal with `Ctrl+x`.
Execute the script
```
python3 scraper.py
```
Navigate to Quickstart and Open file browser. View and download the output file
<p align="center">
<img src="https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/img/filebrowser-demo.gif" alt="Filebrowser" width="500">
</p>
Schedule daily executions with Cronicle
<p align="center">
<img src="https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/img/cronicle-demo.gif" alt="Filebrowser" width="500">
</p>

BIN
workspaces/base-workspace/img/cronicle-demo.gif Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.4 MiB

BIN
workspaces/base-workspace/img/filebrowser-demo.gif Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 847 KiB

4
workspaces/base-workspace/mkdocs/mkdocs.yml
View file

@ -4,14 +4,14 @@
nav:
- Home: README.md
- Docs: docs.md
- Get started: getting-started.md
# ===========================================================
# CONFIGURATION
# ===========================================================
site_name: Base Workspace
site_name: Workspace
repo_url: https://github.com/bluxmit/alnoda-workspaces
site_url: https://alnoda.org
edit_uri: ""

26
workspaces/codeserver-workspace/Dockerfile
View file

@ -1,5 +1,5 @@
ARG docker_registry=docker.io/alnoda
ARG image_tag=18.04-1.0
ARG image_tag=20.04-2.0
FROM ${docker_registry}/base-workspace:${image_tag}
@ -7,17 +7,18 @@ USER root
COPY supervisord-codeserver.conf /etc/supervisord/
COPY ./mkdocs/helpers.py /home/docs/macros
COPY ./mkdocs/home.md /home/docs/docs/pages/home/
COPY ./mkdocs/IDE.jpg /home/docs/docs/pages/home/home/
COPY ./mkdocs/README.md /home/docs/docs/README.md
COPY ./mkdocs/IDE.jpg /home/docs/docs/assets/home/
COPY README.md /home/docs/docs/docs.md
RUN echo "------------------------------------------------------ code-server" \
&& mkdir -p -m 777 /opt/codeserver \
&& cd /opt/codeserver && nodeenv --node=12.18.3 --npm=6.0.0 env \
&& cd /opt/codeserver && . env/bin/activate && npm install -g --unsafe-perm code-server@3.10.2 \
&& apt-get install -y build-essential pkg-config \
&& mkdir -p -m 777 /opt/codeserver \
&& cd /opt/codeserver && nodeenv --node=16.15.0 --npm=1.0.10 env \
&& cd /opt/codeserver && . env/bin/activate && npm install -g yarn && yarn global add code-server@4.4.0 \
&& mkdir -p -m 777 /home/project \
&& mkdir -p -m 777 /opt/codeserver/data \
&& mkdir -p -m 777 /opt/codeserver/extensions \
&& mkdir -p -m 777 mkdir /opt/vscode/extensions \
&& mkdir -p -m 777 /var/log/codeserver \
&& echo "------------------------------------------------------ utils" \
&& rm -rf /home/abc/utils || true \
@ -27,14 +28,17 @@ RUN echo "------------------------------------------------------ code-server" \
&& echo "------------------------------------------------------ user" \
&& chown -R abc /home/project \
&& chown -R abc /opt/codeserver \
&& chown -R abc /opt/codeserver/data \
&& chown -R abc /opt/codeserver/extensions \
&& chown -R abc /opt/vscode \
&& chown -R abc /home/docs \
&& chown -R abc /home/abc/utils \
&& chown -R abc /home/abc/installed-python-packages \
&& find /home -type d | xargs -I{} chown -R abc {} \
&& find /home -type f | xargs -I{} chown abc {}
# USER abc # currently Code-server does not work undder abc
USER abc
COPY code-server-run.sh /opt/codeserver/code-server-run.sh
COPY code-server-run.sh /opt/codeserver/code-server-run.sh

621
workspaces/codeserver-workspace/README.md
View file

@ -3,46 +3,52 @@
</p>
# Code-server workspace
General-purpose dockerized workspace - an environment fully isolated inside a docker container. It can run anywhere, can be started and stopped, moved to another machine, archived
to file or restored, pushed to docker registry, started on a cloud server.
General-purpose dockerized development environment. Fully isolated inside a docker container.
Includes code editor, terminal, scheduler and filebrowser.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-collage-sm.jpg" alt="Collage">
</p>
#### Try it out
## Why this images
1. If you need isolated dev environment where you can code and install packages and apps without affecting the base operating system.
2. If you want self-hosted remote development environment on the Rasberri Pi.
## Start
```
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/codeserver-workspace
```
## Contents
and open [localhost:8020](http://localhost:8020) in browser.
* [About](#about)
* [Code Editor](#code-editor)
* [Why workspace in docker](#why-workspace-in-docker)
* [Launch Workspace](#launch-workspace)
* [Workspace terminal](#workspace-terminal)
* [Multiple workspaces](#multiple-workspaces)
* [Understanding ports](#understanding-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)
## Features
## About
- Workspace own UI. Launch all workspace tools from one place. Customize to your yown needs, include docs.
- [**Code-server**](https://github.com/cdr/code-server) - open source version of popular Visual Studio Code IDE. Codeserver has
VS-Code extensions and works in browser.
- [**Terminal**](https://github.com/tsl0922/ttyd) - secure browser-based terminal.
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- [**Cronicle**](https://github.com/jhuckaby/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**](https://github.com/vercel/serve) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
- [**Ungit**](https://github.com/FredrikNoren/ungit) - rings user friendliness to git without sacrificing the versatility of it.
- [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) - create awesome documentation for your 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.
- **Ubuntu 20.4** with the following CLI apps installed:
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow, lazygit
- curl, wget, telnet, jq
- nano, vim, mc
- ncdu, htop, glances, vizex
- supervisord
- cron
The Workspace contains browser-based Visual Studio Code, and several browser-based tools that make it more convenient to work from inside a docker container.
## Docs
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](../ubuntu-workspace/docs/workspaces.md).
<div align="center" style="font-style: italic;">
Demo: Code-server workspace
@ -50,563 +56,4 @@ The Workspace contains browser-based Visual Studio Code, and several browser-bas
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-wid-demo.gif" alt="WID demo" width="900">
</p>
**Tools with UI**
- Workspace own UI. Launch all workspace tools from one place. Customize to your yown needs, include docs.
- [**Code-server**](https://github.com/cdr/code-server) - open source version of popular Visual Studio Code IDE. Codeserver has
VS-Code extensions and works in browser. This means it can run inside a docker container on local machine or in cloud.
- [**Terminal**](https://github.com/tsl0922/ttyd) - secure browser-based terminal.
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- [**Cronicle**](https://github.com/jhuckaby/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**](https://github.com/vercel/serve) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
- [**Ungit**](https://github.com/FredrikNoren/ungit) - rings user friendliness to git without sacrificing the versatility of it.
- [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) - maintain 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.
**Other:**
- Docker in docker
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow
- curl, wget, telnet, jq,
- nano, vim, mc, ncdu, htop
- supervisord
- cron
*NOTE: This is an alternative workspace to the `workspace-in-docker`. It has all the features ot the latter, except for the
different implementation of the Visual Studio Code.*
## Code Editor
The main code editor of this workspace is [Code-server](https://github.com/cdr/code-server) - an open-source version of popular Visual Studio Code IDE.
despite Code-server is a browser-based code editor, it is fast, responsive, and full-featured. It features code highlighting, autocompletion,
rendering of notebooks has a tree-based file browser, and many color themes.
You can install any extension from [open-vsx.org](https://open-vsx.org/) that has hundreeds of extensions for VS Code compatible editors.
The IDE is already configured to make code highlighting for many programming languages and file types.
<div align="center" style="font-style: italic;">
Demo: Code-server
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-demo.gif" alt="Code-server demo" width="900">
</p>
## Why workspace in docker
Code-server workspace - is a completely self-contained and fully isolated development environment, that runs inside a docker container.
This image includes everything necessary to start coding right away. To usethe workspace, you don't need to install or use any other tools, apart from docker itself.
Workspace can be used on a laptop, PC or launched on the remote server with HTTPS and authentication. Can be shared, backed up, and has versions.
Very convenient if you work on multiple projects and need an easy way to switch between them.
Read in detail about the [advantages of the dockerized workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/README.md#why-workspace-in-docker)
and the [situations when workspace is a good choice](https://github.com/bluxmit/alnoda-workspaces/blob/main/README.md#use-cases)
**TLDR:** This workspace might be quite useful when you want to:
- Avoid the tedious process of setting dev environment on your laptop
- Work conveniently with multiple IT projects on the same machine
- Be able to move all your work to another machine
- Simple way to start coding
- Run dev environment in cloud and work from any device, being independent of cloud provider
- Back-up entire workspaces with important work, save versions of the workspaces before changes
- Collaborate with colleagues by sharing the entire workspace or run it in the cloud
- Move from dev to POC in minutes
- Make experiments (try new packages, versions, frameworks) without risking affecting existing environment
- With a single command start, stop and resume job schedules, related to the same project
- Create a custom dev environment for your team, and help new-comers to save time on setting up their environments
- Move dev environment back and forth between powerful Windows PC and macOS laptop
## Launch Workspace
Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands,
no need to learn any new tools.
In order to avoid confusion, the following convention is adopted:
```sh
command to execute outside of the workspace
```
> `command to execute inside the workspace (after entering running docker container)`
To start a workspace simply execute in terminal
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/codeserver-workspace
```
*(It is recommended to run workspace in the daemon mode)*
***Open [http://localhost:8020](http://localhost:8020)***
Workspace has its own UI, which includes quiklaunch (home) page and documentation pages.
From the quiklaunch you can open any workspace tool. Documentation pages you modify in order
to document the project, workspace use and setup.
### Workspace terminal
There are several ways how to work with terminal of the the workspace:
- built-it in-browser terminal
- use terminal provided by in-browser IDE [http://localhost:8025](http://localhost:8025) ([unless other ports are mapped](#multiple-workspaces))
- ssh into the running the docker container (of the workspace) from your terminal
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/base-workspace/img/base-workspace-terminal.gif" alt="Base-Workspace terminal" width="750">
</p>
If you want to enter running workspace container from your terminal execute:
```sh
docker exec -it space-1 /bin/zsh
```
If you don't want to use z-shell
```
docker exec -it space-1 /bin/bash
```
**NOTE** currently this workspace runs under the root user!
### Multiple workspaces
Every workspace requires range of ports. If one workspace is up and running, the ports 8020-8035 are taken.
Code-server workspace itself uses 9 ports (8020-8028), but it is recommended to map several extra ports just in case. Having extra ports,
you can always launch new applications on these ports, and they will be immediately exposed outside of the workspace.
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-8055:8020-8035 -e ENTRY_PORT=8040 alnoda/codeserver-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.
### Understanding ports
The workspace was started with a port range mapping ***-p 8020-8035***.
This is because workspace contains a set of applications with browser-based UI
| Port | Application |
| --------- | ------------------------- |
| 8020 | Workspace UI |
| 8021 | Filebrowser |
| 8022 | Static file server |
| 8023 | Cronicle |
| 8024 | Ungit |
| 8025 | VS-Code (Code-server) |
| 8026 | Terminal |
| 8027 | Midnight Commander |
| 8028 | Htop |
You don't need to memorize these ports. Workspace has UI from where you can open any of these applications.
Open [localhost:8020](http://localhost:8020), and from there open other applications included in the workspace.
<div align="center" style="font-style: italic;">
Demo: Workspace UI
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-ui.png" alt="codeserver-ui.png" width="750">
</p>
The rest of the ports from the port range can be used in order to expose optional applications, or applications you might
install in future. So we map several extra ports just inn case.
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-8035:8020-8035 -p 8080:8080 alnoda/codeserver-workspace
```
You can add multiple port mappings:
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 8080:8080 -p 443:443 alnoda/codeserver-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-workspace-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-8035:8020-8035 -v /var/run/docker.sock:/var/run/docker.sock alnoda/codeserver-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.
#### Unsecure remote workspace
The simplest deployment of the workspace 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-8035:8020-8035 -e WRK_HOST="<ip-of-your-remote-server>" alnoda/codeserver-workspace
```
**NOTE:** When running workspace on the remote server, add envronmental variable `-e WRK_HOST="<ip-of-your-remote-server>"`.
Workspace UI needss this variable to know how redirect properly to the workspace applications' UIs.
Open in your browser `<ip-of-your-remote-server>:8020`
If docker-in-docker is required, then
```
docker run --name space-1 -d -p 8020-8035:8020-8035 -e WRK_HOST="<ip-of-your-remote-server>" -v /var/run/docker.sock:/var/run/docker.sock alnoda/codeserver-workspace
```
This way launches workspace in cloud, but such workspace is not secure, everyone who knows IP of your server will be able to use it.
#### Secure remote workspace
*You might want to restrict access to the workspace, and secure encrypted communication with the workspace*
Workspace contains utility that will generate everything needed to launch the workspace in cloud in a secure way, with authentication and with TLS.
If you want to run workspace on the remote server securely, start Code-server workspace on your local laptop first, open its terminal and
use utility `/home/abc/utils/remote.py` to generate create docker-compose project with TLS certificates. Simply execute
> `python /home/abc/utils/remote.py --workspace="codeserver-workspace" --port="8020" --host="68.183.69.198" --user="user1" --password="pass1"`
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
After the command is executed, you will see folder `/home/abc/utils/remote` is created. Download it out from the workspace to the local environment using the Filebrowser:
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-remote-gen.gif" alt="generate-remote.gif" width="750">
</p>
. Copy this folder to the remote server where you want to launch the Python workspace.
You can use cyberduck or [scp](https://kb.iu.edu/d/agye). ssh to the server, cd to the directory you copied and execute
```sh
docker-compose up -d
```
That's it, you workspace is running securely on the remote server, using
self-signed TLS certificates for encrypted https communication between you laptop and the remote workspace, and authentication is added.
**NOTE:** The HTTPS is with self-signed certificate, and your browser will show a warning, asking you to accept the risk
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/accept-risks.png" alt="accept-risk" width="750">
</p>
After you accept the risk, authentication window will appear asking you the user and password, that you have set as<ANY_USER_NAME>, <ANY_USER_PASSWORD>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/auth.png" alt="auth" width="750">
</p>
## Use Workspace
Among the common actions you'd do in the workspace are
- installation of new applications and runtimes
- edit files, write code, scripts
- build, compile and execute code
- start/stop applications and services
- schedule tasks and scripts
- process data
### Install applications
Use workspace workspace terminal to install new applications.
For example, in order to install [Emacs text editor](https://www.gnu.org/software/emacs/) open workspace terminal, and execute
> `sudo apt install emacs`
### Schedule jobs with Cron
Schedule execution of any task with cron - a time-based job scheduler in Unix-like computer operating systems.
Open workspace terminal, and execute
> `crontab -e`
*(chose [1] nano as editor on the first time)*
In the end of the opened file add line
> `* * * * * echo $(whoami) >> /home/cron.txt`
This will print every minute username to file */home/cron.txt* . *(Hit Ctrl+X to exit nano)*
Hint: example of cron job definition:
```
.---------------- minute (0 - 59)
| .------------- hour (0 - 23)
| | .---------- day of month (1 - 31)
| | | .------- month (1 - 12) OR jan,feb,mar,apr ...
| | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
| | | | |
* * * * * command to be executed
```
**NOTE** you can disconnect from the image and close terminal - cron will continue working.
> Instead of cron you might want to use Cronicle - a tool with Web UI, and a great list of features
> that will provide you with the dashboard, list of executions and statistics, even let you ser limis
> on resources for each jobs, and create depenndencies between jobs.
### Python
Python and Pip are installed. To use python console, open workspace terminal and execute
> `python`
install python package with pip, for
> `pip install pandas`
If you are planning to work with python, we recommend to install IPython, that provides a rich toolkit to help
you make the most of using Python interactively. Install and start ipython
> ```pip install ipython```
> `ipython`
### Node.js
We recommend to use nodeenv to create different node environments.
For example, open workspace terminal, create folder npmgui, and activate environment with node v. 12.18.3 and npm v.6.0.0
> `cd /home`
> `mkdir npmgui; cd npmgui`
> `nodeenv --node=12.18.3 --npm=6.0.0 env`
Let's install package and start node application
> `. env/bin/activate && npm i -g npm-gui`
> `npm-gui 0.0.0.0:8030`
Open your browser on http://localhost:8030/
**NOTE:** If you close terminal, the application will stop. See how to [start applications that reamin live after closing a workspace terminal](#run-applications-and-services-inside-the-workspace)
### Run applications and services inside the workspace
If you want application to keep running after workspace terminal is closed start it with **"&!"** at the end.
For example, in the last section we started *npm-gui* tool with command `npm-gui 0.0.0.0:8030`. If you close the workspace terminal,
this application witll stop running. To keep it running after terminal is closed, execute
> `npm-gui 0.0.0.0:8030 &!`
Now, if you disconnect from the workspace and close terminal, the application will continue running in the workspace, untill [workspace is stopped](#start-and-stop-workspaces).
## Manage workspaces
Workspace is just a docker container. You can start, stop, delete and do anything you can do with docker images and containers.
There are two concepts to keep in mind: **images** and **containers**. Images are workspace blueprints. For example, **alnoda/codeserver-workspace** -
is an image. When you execute this command
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/codeserver-workspace
```
you create container called **space-1** from the image **alnoda/codeserver-workspace**. You can create any number of containers, but you need to
[map different ports to each of them](#multiple-workspaces).
Container - is your workspace. You can start, stop and delete them. You can run multiple workspace containers at the same time, or work with
one workspace at a time.
From the workspace (which is a container) you can create new image. This is called **commit docker image**.
Essentially, this means *"take my workspace and create new image with all the changes I've done in my workspace*"
### Start and stop workspaces
The workspace started in daemon mode will continue working in the background.
See all the running docker containers
```
docker ps
```
Stop workspace
```sh
docker stop space-1
```
Workspace is stopped. All the processes and cron jobs are not running.
See all docker conntainers, including stopped
```
docker ps -a
```
Start workspace again. Processes and cron jobs are resumed.
```sh
docker start space-1
```
Delete workspace container (all work will be lost)
```
docker rm space-1
```
### Create new workspace image
Having made changes, you can commit them creating new image of the workspace. In order to create new workspace image with the
name "space-image" and version "0.2" execute
```
docker commit space-1 space-image:0.2
```
Run new workspace with
```
docker run --name space2 -d space-image:0.2
```
The new workspace accommodates all the changes that you've made in your space-1. Hence you can have versions of your workspaces.
Create different versions before the important changes.
### Manage workspace images
See all docker images
```
docker images
```
Delete workspace image entirely
```
docker rmi -f alnoda/codeserver-workspace
```
**NOTE:** you cannot delete image if there is a running container created from it. Stop container first.
### Save and load workspace images
After you commit workspace container, and create new image out of it, you can push it to your docker registry or save it in a file.
#### Save workspace in a file
Assuming you created new image **space-image:0.4** from your workspace, you can save it as a tar file
```
docker save space-image:0.4 > space-image-0.4.tar
```
We can delete the image with
```
docker rmi -f space-image:0.4
```
And restore it from the tar file
```
docker load < space-image-0.4.tar
```
#### Push workspace to a registry
A better way to manage images is docker registries. You can use docker registries in multiple clouds. They are cheap annd very convenient.
Check out for example, [Registry in DigitalOcean](https://www.digitalocean.com/products/container-registry/) or in [Scaleway container registry](https://www.scaleway.com/en/container-registry/). There are more.
Pushing image to registry is merely 2 extra commands: 1) tag image; 2) push image
You will be able to pull image on any device, local or cloud.
### Move workspace to the cloud
Ease of running workspace in cloud, and ability to move workspaces between local machine and remote server -
is one of the main features of the workspace, and the reasonn why the workspace is entirely in docker.
It is often a case that experiment, which started on personal notebook require more computational
resources, must be running for a long period of time, or executed periodically. All of these cases are
the reasons to move a workspace to the cloud server. Usually it is a hassle, but this workspace can be moved
to the remote server easily.
The easiest way to move workspace to the cloud is to get your private docker registry. Then moving a workspace from a laptop to
a remote server is only 3 commands:
1. [Commit workspace to the a image](#create-new-workspace-image)
2. [Push workspace to your docker registry](https://docs.docker.com/engine/reference/commandline/push/)
3. ssh to remote server, and [run workspace there](#run-on-remote-server)
If you don't want to use container registry, then there are 2 steps more involved:
1. [Commit workspace to the a image](#create-new-workspace-image)
2. [Save image to file](#create-new-workspace-image)
3. Copy file to remote server. There are many options:
- Launch filexchange workspace on the remote server
- Use [cyberduck](https://cyberduck.io/)
- use [scp](https://linuxize.com/post/how-to-use-scp-command-to-securely-transfer-files/)
4. [Load workspace image from file](#save-and-load-workspace-images) on the remote server
5. [Start workspace on the remote server](#run-on-remote-server)
## Workspace Documentation
Workspace can easily be customized for your specific needs. You can also use Workspace for a complex project, and might need a
tool to write remarks, plans, action plans. As well as architectural artefacts for the components you wish to implement. Often it is
also needed to store somewhere snippets of code or shell commands that you often use in your work. It would be uncomfortable to use extra
tool or solution outside of the Workspace to store such remarks.
Because Workspace is a complete self-contained environment, it include tools to make remarks, plans, store pieces of code, write anything,
and even build complete static documentation websites that you can host on GitHub Pages for example.
[MkDocs](https://www.mkdocs.org/) is a part of the workspace, and its dev server is up and running every time you start the Workspace. In fact,
the workspace UI (port 8020 by default) - is served by the MkDocs dev server.
You can easily modify the UI, add more pages or update existing pages. The changes will be updated immediately without the need to do anything.
MkDocs project is located in the `/home/docs/` folder. It has subfolder called `docs` (so it is `/home/docs/docs/`) where all the Markdown documents
are stored. Simply create new `.md` file there. And add reference about this file to the MkDocs config `/home/docs/mkdocs.yml`. You will see that
the new page has appeared in your Workspace UI - it has live reload, and you dont need to do annything, just write in the markdown files.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-docs.gif" alt="workspace-docs" width="900">
</p>
You can easily build beautiful static website from this documentation
> `cd /home/docs/ && mkdocs build -d /home/static-server/my-doc-website`
The resulting HTML website is in folder `/home/static-server/my-doc-website`, you can view it with Static File Server and download to local
with Filebrowser.
You can make even more stunning documentation websites with advanced Markdown features using [MkDocs-Magicspace](https://mkdocs-magicspace.alnoda.org/).
</p>

108
workspaces/codeserver-workspace/docs/getting_started.md Normal file
View file

@ -0,0 +1,108 @@
# Getting started
## Intro
The main feature of the workspace is IDE, a browser-based VS-Code version. Often IDE alone is not enough for convenient software development.
In addition, workspace includes full-screen terminal, file manager, and task scheduler. This workspace is based on the Ubuntu 20 docker image,
with typical terminal applications, such as Git installed.
## Quicklaunch
From the quicklaunch page you can open workspace tools, such as code editor or terminal
<div align="center" style="font-style: italic;">
Demo: Workspace UI
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/wid-ui.png" alt="wid-ui.png" width="750">
</p>
## Code Editor
The main code editor of this workspace is [Code-server](https://github.com/cdr/code-server) - an open-source version of popular Visual Studio Code IDE.
despite Code-server is a browser-based code editor, it is fast, responsive, and full-featured. It features code highlighting, autocompletion,
rendering of notebooks has a tree-based file browser, and many color themes.
You can install any extension from [open-vsx.org](https://open-vsx.org/) that has hundreeds of extensions for VS Code compatible editors.
The IDE is already configured to make code highlighting for many programming languages and file types.
<div align="center" style="font-style: italic;">
Demo: Code-server
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/codeserver-workspace/img/codeserver-demo.gif" alt="Code-server demo" width="900">
</p>
## Terminal
Workspace has full-size browser-base terminal
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/base-workspace/img/base-workspace-terminal.gif" alt="Base-Workspace terminal" width="750">
</p>
## Install applications
Use workspace workspace terminal to install new applications.
Install with ```sudo apt install```. The default *abc* user is allowed to install packages.
For example, in order to install [Emacs text editor](https://www.gnu.org/software/emacs/) open workspace terminal, and execute
```
sudo apt-get update
sudo apt install emacs
```
## Python
Python and Pip are installed. To use python console, open workspace terminal and execute
> `python3`
install python package with pip, for
> `pip install pandas`
If you are planning to work with python, we recommend to install IPython, that provides a rich toolkit to help
you make the most of using Python interactively. Install and start ipython
> ```pip install ipython```
> `ipython`
## Node.js
We recommend to use nodeenv to create different node environments.
For example, open workspace terminal, create folder npmgui, and activate environment with node v. 12.18.3 and npm v.6.0.0
> `cd /home`
> `mkdir npmgui; cd npmgui`
> `nodeenv --node=12.18.3 --npm=6.0.0 env`
Let's install package and start node application
> `. env/bin/activate && npm i -g npm-gui`
> `npm-gui 0.0.0.0:8030`
Open your browser on http://localhost:8030/
**NOTE:** If you close terminal, the application will stop. See how to [start applications that reamin live after closing a workspace terminal](#run-applications-and-services-inside-the-workspace)
### Run applications and services inside the workspace
If you want application to keep running after workspace terminal is closed start it with **"&!"** at the end.
For example, in the last section we started *npm-gui* tool with command `npm-gui 0.0.0.0:8030`. If you close the workspace terminal,
this application witll stop running. To keep it running after terminal is closed, execute
> `npm-gui 0.0.0.0:8030 &!`
Now, if you disconnect from the workspace and close terminal, the application will continue running in the workspace, untill [workspace is stopped](#start-and-stop-workspaces).
## Scheduler
Cronicle allows scheduling scripts, jobs and tasks and it has nice UI
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/cronicle.gif" alt="Cronicle" width="750">
</p>

29
workspaces/codeserver-workspace/mkdocs/home.md → workspaces/codeserver-workspace/mkdocs/README.md
View file

@ -1,8 +1,11 @@
<style>
/* These styles apply only to this page! */
.md-content__button {
display: none;
}
.md-content__button {
display: none;
}
.md-sidebar--secondary{
display: none !important;
}
.md-typeset h1 {
line-height: 0;
margin: 0;
@ -57,49 +60,49 @@
{
"env": "IDE_URL",
"name": "IDE",
"image": "IDE.jpg",
"image": "assets/home/IDE.jpg",
"description": "Browser-based version of Visual Studio Code. Develop in any language, install hundreeds of extensions"
},
{
"env": "TERMINAL_URL",
"name": "Terminal",
"image": "Terminal.png",
"description": "Full-fledged browser-based terminal with Z-shell"
"image": "assets/home/Terminal.png",
"description": "Full-fledged WEB-based Command Line Interface"
},
{
"env": "FILEBROWSER_URL",
"name": "File Browser",
"image": "Filebrowser.png",
"image": "assets/home/Filebrowser.png",
"description": "Browse, upload and download files and folders to and from the Workspace"
},
{
"env": "CRONICLE_URL",
"name": "Cronicle",
"image": "Cronicle.jpg",
"image": "assets/home/Cronicle.jpg",
"description": "Schedule jobs, manage schedules, observe and monitor executions (user/pass - admin/admin)"
},
{
"env": "UNGIT_URL",
"name": "Ungit",
"image": "Ungit.jpg",
"image": "assets/home/Ungit.jpg",
"description": "Manage Git repositories and work flow using beautiful UI"
},
{
"env": "STATICFS_URL",
"name": "Static File Server",
"image": "Static-server.png",
"image": "assets/home/Static-server.png",
"description": "Serve any static websites like a breeze"
},
{
"env": "MC_URL",
"name": "M.Commander",
"image": "MC.jpg",
"image": "assets/home/MC.jpg",
"description": "Feature rich visual file manager with internal text viewer and editor"
},
{
"env": "HTOP_URL",
"name": "Process monitor",
"image": "Htop.jpg",
"name": "Resource monitor",
"image": "assets/home/Htop.jpg",
"description": "Monitor running process and resource utilization"
}
]

24
workspaces/ide-workspace/README.md
View file

@ -13,12 +13,12 @@ Includes code editor, terminal, scheduler and filebrowser.
## Why this images
1. If you need isolated dev environment where you can code and install packages and apps without affecting the base operating system.
2. If you want self-hosted cloud development environment.
2. If you want self-hosted remote development environment on your Rasberri Pi.
## Start
```
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/ide-workspace
```
and open [localhost:8020](http://localhost:8020) in browser.
@ -28,18 +28,32 @@ and open [localhost:8020](http://localhost:8020) in browser.
- [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has
VS-Code extensions and works in browser. This means it can run inside a docker container on local machine or in cloud. A lot of beautiful color themes and many common plugins are already installed to save time.
- [**Terminal**](https://github.com/tsl0922/ttyd) - secure browser-based terminal.
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, upload and donload files to/from the workspace
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- [**Cronicle**](https://github.com/jhuckaby/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**](https://github.com/vercel/serve) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
- [**Ungit**](https://github.com/FredrikNoren/ungit) - rings user friendliness to git without sacrificing the versatility of it.
- [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) - create awesome documentation for your 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.
- Quicklaunch UI with getting started tutorial
- **Ubuntu 20.4** with the following CLI apps installed:
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow, lazygit
- curl, wget, telnet, jq
- nano, vim, mc
- ncdu, htop, glances, vizex
- supervisord
- cron
## Docs
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](docs/features.md).
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](../ubuntu-workspace/docs/workspaces.md).
<div align="center" style="font-style: italic;">
Demo: Workspace in docker
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/workspace-in-docker/img/wid-demo.gif" alt="WID demo" width="900">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/wid-demo.gif" alt="WID demo" width="900">
</p>

14
workspaces/ide-workspace/docs/getting-started.md
View file

@ -1,19 +1,11 @@
# IDE-workspace: getting started
# Getting started
## Intro
The main feature of the workspace is IDE, a browser-based VS-Code version. But IDE alone is not enough for convenient software development.
The main feature of the workspace is IDE, a browser-based VS-Code version. Often IDE alone is not enough for convenient software development.
In addition, workspace includes full-screen terminal, file manager, and task scheduler. This workspace is based on the Ubuntu 20 docker image,
with typical terminal applications, such as Git installed.
<div align="center" style="font-style: italic;">
Demo: Workspace in docker
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/wid-demo.gif" alt="WID demo" width="900">
</p>
## Quicklaunch
From the quicklaunch page you can open workspace tools, such as code editor or terminal
@ -71,7 +63,7 @@ sudo apt install emacs
## Python
Python and Pip are installed. To use python console, open workspace terminal and execute
> `python`
> `python3`
install python package with pip, for

5
workspaces/java-workspace/Dockerfile
View file

@ -1,12 +1,13 @@
ARG docker_registry=docker.io/alnoda
ARG image_tag=18.04-1.0
ARG image_tag=2.0
FROM ${docker_registry}/workspace-in-docker:${image_tag}
FROM ${docker_registry}/codeserver-workspace:${image_tag}
USER root
RUN apt-get -y update \
&& echo "------------------------------------------------------ java 8" \
&& sudo apt-get install -y openjdk-8-jre \
&& apt-get install -y openjdk-8-jdk \
&& echo "------------------------------------------------------ maven" \
&& wget https://dlcdn.apache.org/maven/maven-3/3.8.5/binaries/apache-maven-3.8.5-bin.tar.gz -P /tmp \
&& tar xf /tmp/apache-maven-3.8.5-bin.tar.gz \

23
workspaces/java-workspace/docs/get-started.md Normal file
View file

@ -0,0 +1,23 @@
Open terminal and check Java version
```
java -version
```
Open IDE and create file `Main.java` with the following content
```
public class Main {
public static void main(String[] args) {
System.out.println("Hello World");
}
}
```
Use terminal to compile and execute
```
cd /home/project
javac Main.java
java Main
```

26
workspaces/php-workspace/Dockerfile
View file

@ -0,0 +1,26 @@
ARG docker_registry=docker.io/alnoda
ARG image_tag=2.0
FROM ${docker_registry}/codeserver-workspace:${image_tag}
USER root
RUN echo "------------------------------------------------------ PHP " \
&& add-apt-repository -y ppa:ondrej/php \
&& apt-get -y update \
&& apt -y install php8.1 \
&& echo "------------------------------------------------------ modules" \
&& apt-get install -y php8.1-cli php8.1-common php8.1-mysql php8.1-zip php8.1-gd php8.1-mbstring php8.1-curl php8.1-xml php8.1-bcmath \
&& echo "------------------------------------------------------ Composer" \
&& cd /tmp && php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" \
&& php composer-setup.php \
&& php -r "unlink('composer-setup.php');" \
&& mv ./composer.phar /usr/bin/composer
USER abc

47
workspaces/ubuntu-workspace/README.md
View file

@ -1,9 +1,10 @@
<p align="center">
<img src="https://github.com/bluxmit/alnoda-workspaces/blob/main/img/Alnoda-white.svg" alt="Alnoda logo" width="150">
</p>
</p>
# Ubuntu-workspace
Containerized terminal environment. Essentially Ubuntu 20.04 docker image with typical terminal applications added.
Containerized Linux terminal environment. Essentially Ubuntu 20.04 docker image extended with typical console apps installed, such as Git,
file browsers and system monitors.
Start
@ -17,22 +18,34 @@ Enter workspace
docker exec -it --user=root space-1 /bin/zsh
```
## Features
- **Ubuntu 20.4** with the following apps
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow, lazygit
- curl, wget, telnet, jq
- nano, vim, mc
- ncdu, htop, glances, vizex
- supervisord
- cron
## Why this image
If you need to isolate something without polluting main environment. This image simply adds typical console applications to
the Ubuntu 20.04 image:
If you need to isolate some work without polluting main environment.
## Docs
See our guides on [**getting started**](docs/getting-started.md) and [**advanced features**](docs/workspaces.md).
<div align="center" style="font-style: italic;">
Demo: Ubuntu-workspace
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/ubuntu-workspace.gif" alt="Ubuntu workspace" width="900">
</p>
-
- [Fig](https://github.com/withfig/autocomplete). adds autocomplete to the terminal.
- [spacemacs](https://www.spacemacs.org/)
- [hyper](https://github.com/vercel/hyper)
- [xplr](https://github.com/sayanarijit/xplr)
- [vizex](https://github.com/bexxmodd/vizex)
- [lazygit](https://github.com/jesseduffield/lazygit)
- [gitui](https://github.com/extrawurst/gitui)
- [bashtop](https://github.com/aristocratos/bashtop)
- [amp](https://github.com/jmacdonald/amp)
- [fff](https://github.com/dylanaraps/fff)
- [slap](https://github.com/slap-editor/slap)
- [glow](https://github.com/charmbracelet/glow)

14
workspaces/ubuntu-workspace/docs/candidates.md Normal file
View file

@ -0,0 +1,14 @@
# Potential future extentions
- [Fig](https://github.com/withfig/autocomplete). adds autocomplete to the terminal.
- [spacemacs](https://www.spacemacs.org/)
- [hyper](https://github.com/vercel/hyper)
- [xplr](https://github.com/sayanarijit/xplr)
- [vizex](https://github.com/bexxmodd/vizex)
- [lazygit](https://github.com/jesseduffield/lazygit)
- [gitui](https://github.com/extrawurst/gitui)
- [bashtop](https://github.com/aristocratos/bashtop)
- [amp](https://github.com/jmacdonald/amp)
- [fff](https://github.com/dylanaraps/fff)
- [slap](https://github.com/slap-editor/slap)
- [glow](https://github.com/charmbracelet/glow)

67
workspaces/ubuntu-workspace/docs/getting-started.md Normal file
View file

@ -0,0 +1,67 @@
# Getting started
## Start
```sh
docker run --name space-1 -d alnoda/ubuntu-workspace
```
Now you can ssh into the running workspace container
```sh
docker exec -it space-1 /bin/zsh
```
## Root user
ssh into the running workspace container as root user
```sh
docker exec -it --user=root space-1 /bin/zsh
```
## Examples
Explore file system with Midnight Commander
> ```mc```
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/mc.png" alt="Moonlignt commander" width="750">
</p>
Launch system-monitor, process-viewer and process-manager
```
htop
```
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/htop.png" alt="Htop" width="750">
</p>
Explore file/folder sizes
```
ncdu
```
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/ncdu.png" alt="Htop" width="750">
</p>
Text editors ```vim```, ```nano``` and ```mcedit``` are available. For example, clone git repo and edit python file with nano
```
git clone https://github.com/dimaba/sendmail.git
cd sendmail
nano sendmail.py
```
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/nano.png" alt="Htop" width="750">
</p>
```
mcedit sendmail.py
```
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ubuntu-workspace/img/mcedit.png" alt="Htop" width="750">
</p>
## Docker in docker
If you want to use docker, check out **ubuntu-docker-workspace**. It is the same, but with docker-in-docker.

0
workspaces/ubuntu-workspace/doc/remote-wid.md → workspaces/ubuntu-workspace/docs/remote-wid.md
View file

366
workspaces/ide-workspace/docs/features.md → workspaces/ubuntu-workspace/docs/workspaces.md
View file

@ -1,68 +1,60 @@
# Workspaces
## Contents
* [All features](#all-features)
* [Why workspace in docker](#why-workspace-in-docker)
* [Intro](#intro)
* [Why workspace in docker](#why-ide-workspace)
* [Workspace UIs](#workspace-uis)
* [Quickstart](#quickstart)
* [Code editor](#code-editor)
* [Terminal](#terminal)
* [Task scheduler](#task-scheduler)
* [Launch Workspace](#launch-workspace)
* [Workspace terminal](#workspace-terminal)
* [Multiple workspaces](#multiple-workspaces)
* [Understanding ports](#understanding-ports)
* [Command line applications](#command-line-applications)
* [Install apps](#install-apps)
* [Schedule jobs with cron](#schedule-jobs-with-cron)
* [Python](#python)
* [Node.js](#node.js)
* [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)
* [Extend workspaces](#extend-workspaces)
* [Workspace tree](#workspace-tree)
* [Java](#java)
* [Run applications permanently](#run-applications-permanently)
* [Self-hosted workspace](#self-hosted-workspace)
* [Unsecure remote workspace](#unsecure-remote-workspace)
* [Secure remote workspace](#secure-remote-workspace)
* [Workspace Documentation](#workspace-documentation)
* [Create documentation](#create-documentation)
* [Customize Workspace](#customize-workspace)
* [Customize Quickstart](#customize-quickstart)
## Intro
## All features
The full lost of workspace features
**Tools with UI**
- Workspace own UI. Launch all workspace tools from one place. Customize to your yown needs, include docs.
- [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has
VS-Code extensions and works in browser. This means it can run inside a docker container on local machine or in cloud. A lot of beautiful color themes and many common plugins are already installed to save time.
- [**Terminal**](https://github.com/tsl0922/ttyd) - secure browser-based terminal.
- [**FileBrowser**](https://github.com/filebrowser/filebrowser) - manage files and folders inside the workspace, and exchange data between local environment and the workspace
- [**Cronicle**](https://github.com/jhuckaby/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**](https://github.com/vercel/serve) - view any static html sites as easy as if you do it on your local machine. Serve static websites easily.
- [**Ungit**](https://github.com/FredrikNoren/ungit) - rings user friendliness to git without sacrificing the versatility of it.
- [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) - maintain 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.
- **Ubuntu 20.4** with the following apps
- [Zsh](https://www.zsh.org/), [Oh my Zsh](https://ohmyz.sh/)
- Python 3, Pip
- Node/nodeenv
- git, git-flow, lazygit
- curl, wget, telnet, jq
- nano, vim, mc
- ncdu, htop, glances, vizex
- supervisord
- cron
*NOTE: This is an alternative workspace to the `codeserver-workspace`. It has all the features ot the latter, except for the
different implementation of the Visual Studio Code.*
This doc describes workspaces in docker. Examples are provided for the **ide-workspace** but can be used for other workspaces too.
## Why workspace in docker
Workspace-in-docker - is a completely self-contained and fully isolated development environment, that runs inside a docker container.
This image includes everything necessary to start coding right away. To use Workspace-in-docker, you don't need to install or use any other tools, apart from docker itself.
Workspace in docker - is a completely self-contained and fully isolated development environment, that runs inside a docker container.
Workspace image includes toolset necessary to start coding or doing other tasks right away.
To use workspace in docker, you won't need to install or use any other tools, apart from docker itself.
Workspace can be used on a laptop, PC or launched on the remote server with HTTPS and authentication. Can be shared, backed up, and has versions.
Very convenient if you work on multiple projects and need an easy way to switch between them.
If you work on multiple projects, you can start and stop workspaces, and switch between them.
Isolation in docker prevents from polluting your main environment.
Read in detail about the [advantages of the dockerized workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/README.md#why-workspace-in-docker)
and the [situations when workspace is a good choice](https://github.com/bluxmit/alnoda-workspaces/blob/main/README.md#use-cases)
**TLDR:** This workspace might be quite useful when you want to:
**TLDR:** This workspace might be useful when you want to:
- Avoid the tedious process of setting dev environment on your laptop
- Work conveniently with multiple IT projects on the same machine
- Work conveniently with multiple projects on the same machine
- Be able to move all your work to another machine
- Simple way to start coding
- Run dev environment in cloud and work from any device, being independent of cloud provider
@ -75,10 +67,84 @@ and the [situations when workspace is a good choice](https://github.com/bluxmit/
- Move dev environment back and forth between powerful Windows PC and macOS laptop
## Workspace UIs
Most of the workspaces have UI tools, except for workspaces designed to be used purely from the terminal (such as ubuntu-workspace).
Nearly all the workspaces have quickstart page, code editor, full-size terminal, visual job scheduler, file browser, static file server,
visual git interface.
Different workspaces have other tools with grapthical interfaces.
All UI tools are browser-based.
## Quickstart
From the quicklaunch page you can open workspace tools, such as code editor or terminal. Workspace Quicklaunch UI
is always exposed on the 8020 port
<div align="center" style="font-style: italic;">
Demo: Workspace UI
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/wid-ui.png" alt="wid-ui.png" width="750">
</p>
### Code editor
Code editor of this workspace is [**Eclipse Theia**](https://theia-ide.org/docs/) - an open-source version of popular Visual Studio Code IDE.
despite Eclipse Theia is a browser-based code editor, it is fast, responsive, and full-featured. It features code highlighting, autocompletion,
rendering of notebooks has a tree-based file browser, and a great number of pre-installed color themes.
<div align="center" style="font-style: italic;">
Demo: Eclipse Theia
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/theia.gif" alt="Theia demo" width="900">
</p>
You can install any extension from [open-vsx.org](https://open-vsx.org/) that has hundreeds of extensions for VS Code compatible editors.
The IDE is already configured to make code highlighting for a great number of programming languages and file types. It also has many
popular extensions installed
### Terminal
Workspace has full-size browser-base terminal
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/base-workspace/img/base-workspace-terminal.gif" alt="Base-Workspace terminal" width="750">
</p>
Use workspace workspace terminal to install new applications.
Install with ```sudo apt install```. The default *abc* user is allowed to install packages.
For example, in order to install [Emacs text editor](https://www.gnu.org/software/emacs/) open workspace terminal, and execute
```
sudo apt-get update
sudo apt install emacs
```
### Task scheduler
[Cronicle](https://github.com/jhuckaby/Cronicle) is a multi-server 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.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ansible-terraform-workspace/img/cronicle-ansible.gif" alt="Htop" width="900">
</p>
**NOTE:** Scheduling Ansible playbooks is especially useful if you [launch Workspace on a remote server](#run-on-remote-server) rather than
on your local laptop.
## Launch Workspace
Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands,
no need to learn any new tools.
no need to learn any new tools.
*The further examples will *
In order to avoid confusion, the following convention is adopted:
@ -91,7 +157,7 @@ command to execute outside of the workspace
To start a workspace simply execute in terminal
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/ide-workspace
```
*(It is recommended to run workspace in the daemon mode)*
@ -104,7 +170,7 @@ to document the project, workspace use and setup.
## Workspace terminal
There are several ways how to work with terminal of the the workspace-in-docker:
There are several ways how to work with terminal of the the ide-workspace:
- built-it in-browser terminal
- use terminal provided by in-browser IDE [http://localhost:8025](http://localhost:8025) ([unless other ports are mapped](#multiple-workspaces))
@ -136,7 +202,7 @@ You can work in Ubuntu terminal now. Execute the followinng command to know your
Every workspace requires range of ports. If one workspace is up and running, the ports 8020-8035 are taken.
Workspace-in-docker itself uses 9 ports (8020-8028), but it is recommended to map several extra ports just in case. Having extra ports,
ide-workspace itself uses 9 ports (8020-8028), but it is recommended to map several extra ports just in case. Having extra ports,
you can always launch new applications on these ports, and they will be immediately exposed outside of the workspace.
In order to start another workspace, you either need to stop currently runnning workspace, or to run another workspace
@ -146,14 +212,14 @@ If you are planning to run more than one workspace at the same time, you can run
the different port range, for example
```sh
docker run --name space-2 -d -p 8040-8055:8020-8035 -e ENTRY_PORT=8040 alnoda/workspace-in-docker
docker run --name space-2 -d -p 8040-8055:8020-8035 -e ENTRY_PORT=8040 alnoda/ide-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.
## Understanding ports
The workspace was started with a port range mapping ***-p 8020-8035***.
Usually workspace was started with a port range mapping ***-p 8020-8035***.
This is because workspace contains a set of applications with browser-based UI
| Port | Application |
@ -168,46 +234,132 @@ This is because workspace contains a set of applications with browser-based UI
| 8027 | Midnight Commander |
| 8028 | Htop |
You don't need to memorize these ports. Workspace has UI from where you can open any of these applications.
Other workspaces might have more applications running, and use additional ports. For example **ansible-terraform-workspace** includes
additional GUI application - Ansible Ara
| Port | Application |
| --------- | ------------------------- |
| 8029 | Ansible Ara |
You don't need to memorize these ports. Workspace has UI from where you can open any of the applications.
Open [localhost:8020](http://localhost:8020), and from there open other applications included in the workspace.
<div align="center" style="font-style: italic;">
Demo: Workspace UI
</div>
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/ide-workspace/img/wid-ui.png" alt="wid-ui.png" width="750">
</p>
The rest of the ports from the port range can be used in order to expose optional applications, or applications you might
install in future. So we map several extra ports just inn case.
install in future. So we map several extra ports just in case.
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-8035:8020-8035 -p 8080:8080 alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 8080:8080 alnoda/ide-workspace
```
You can add multiple port mappings:
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 8080:8080 -p 443:443 alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 -p 8080:8080 -p 443:443 alnoda/ide-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-workspace-image))
## Command line applications
Workspace usually includes many CLI tools and apps, such as Git and git tools, console text editors and file browsers and
system monitors.
Specialized workspaces include more CLI applications.
Use workspace terminal to work with CLI apps.
### Install apps
Install new packages with ```sudo apt install```, for example emacs
```
sudo apt install emacs
```
### Schedule jobs with cron
Schedule execution of any task with cron. Create cron task with
```
crontab -e
```
*(chose [1] nano as editor)*
In the end of the opened file add line
> `* * * * * echo $(whoami) >> /home/cron.txt`
This will print every minute username to file */home/cron.txt* . Ctrl+X to exit nano
> ```
> Hint: example of cron job definition:
> .---------------- minute (0 - 59)
> | .------------- hour (0 - 23)
> | | .---------- day of month (1 - 31)
> | | | .------- month (1 - 12) OR jan,feb,mar,apr ...
> | | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
> | | | | |
> * * * * * command to be executed
> ```
**NOTE** you can disconnect from the image and close terminal. cron will continue working.
### Python
Python and Pip are installed. To start python console simply execute
```
python
```
Install python package with pip
```
pip install pandas
```
Install and start ipython
```
pip install ipython
ipython
```
Create and activate virtual environment called 'my_env'
```
mkdir /home/pytest
cd /home/pytest && python -m venv my_env
source my_env/bin/activate
```
### Node.js
Use nodeenv to create different node environments. For example, create folder npmgui, and activate environment with node v. 12.18.3 and npm v.6.0.0
```
cd /home
mkdir npmgui; cd npmgui
nodeenv --node=12.18.3 --npm=6.0.0 env
```
Let's install package and start node application
```
. env/bin/activate && npm i -g npm-gui
npm-gui 0.0.0.0:19011
```
Open your browser on http://localhost:19011/
*(This is why we made a port mapping with "-p 19011:19011")*
> *NOTE* If you close terminal, the application will stop.
> Find how to run applications permanently in the section [Run applications permanently](#run-applications-permanently)
## Manage workspaces
Workspace is just a docker container. You can start, stop, delete and do anything you can do with docker images and containers.
There are two concepts to keep in mind: **images** and **containers**. Images are workspace blueprints. For example, **alnoda/workspace-in-docker** -
There are two concepts to keep in mind: **images** and **containers**. Images are workspace blueprints. For example, **alnoda/ide-workspace** -
is an image. When you execute this command
```sh
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/ide-workspace
```
you create container called **space-1** from the image **alnoda/workspace-in-docker**. You can create any number of containers, but you need to
you create container called **space-1** from the image **alnoda/ide-workspace**. You can create any number of containers, but you need to
[map different ports to each of them](#multiple-workspaces).
Container - is your workspace. You can start, stop and delete them. You can run multiple workspace containers at the same time, or work with
@ -280,7 +432,7 @@ docker images
Delete workspace image entirely
```
docker rmi -f alnoda/workspace-in-docker
docker rmi -f alnoda/ide-workspace
```
**NOTE:** you cannot delete image if there is a running container created from it. Stop container first.
@ -363,7 +515,7 @@ The simplest deployment of the workspace requires only 3 steps:
- ssh to the remote server and start workspace
```
docker run --name space-1 -d -p 8020-8035:8020-8035 -e WRK_HOST="<ip-of-your-remote-server>" alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 -e WRK_HOST="<ip-of-your-remote-server>" alnoda/ide-workspace
```
**NOTE:** When running workspace on the remote server, add envronmental variable `-e WRK_HOST="<ip-of-your-remote-server>"`.
@ -374,7 +526,7 @@ Open in your browser `<ip-of-your-remote-server>:8020`
If docker-in-docker is required, then
```
docker run --name space-1 -d -p 8020-8035:8020-8035 -e WRK_HOST="<ip-of-your-remote-server>" -v /var/run/docker.sock:/var/run/docker.sock alnoda/workspace-in-docker
docker run --name space-1 -d -p 8020-8035:8020-8035 -e WRK_HOST="<ip-of-your-remote-server>" -v /var/run/docker.sock:/var/run/docker.sock alnoda/ide-workspace
```
This way launches workspace in cloud, but such workspace is not secure, everyone who knows IP of your server will be able to use it.
@ -383,12 +535,12 @@ This way launches workspace in cloud, but such workspace is not secure, everyone
*You might want to restrict access to the workspace, and secure encrypted communication with the workspace*
Workspace-in-docker contains utility that will generate everything needed to launch the workspace in cloud in a secure way, with authentication and with TLS.
ide-workspace contains utility that will generate everything needed to launch the workspace in cloud in a secure way, with authentication and with TLS.
If you want to run workspace on the remote server securely, start workspace-in-docker on your local laptop first, open its terminal and
If you want to run workspace on the remote server securely, start ide-workspace on your local laptop first, open its terminal and
use utility `/home/abc/utils/remote.py` to generate create docker-compose project with TLS certificates. Simply execute
> `python /home/abc/utils/remote.py --workspace="workspace-in-docker" --port="8020" --host="68.183.69.198" --user="user1" --password="pass1"`
> `python /home/abc/utils/remote.py --workspace="ide-workspace" --port="8020" --host="68.183.69.198" --user="user1" --password="pass1"`
**NOTE:** you have to specify the correct host (IP of the server you want to run the workspace on), and user and password of your choice.
@ -422,7 +574,88 @@ After you accept the risk, authentication window will appear asking you the user
</p>
## Workspace Documentation
## Extend workspaces
### Workspace tree
Most of the workspaces are built from other workspaces, and include all the features of the parent workspaces.
For example, ansible-terrafrorm-workspace is built from ide-workspace, ide-workspace is built from base-workspace,
and the latter is built from ubuntu-workspace.
ubuntu-workspace -> base-workspace -> ide-workspace -> ansible-terrafrorm-workspace
Ansible-terrafrorm-workspace has all the features of ide-workspace, base-workspace and ubuntu-workspace.
### Java
Java is not installed in some of the workspaces. It can be installed as easy as
```
sudo apt-get install openjdk-8-jre
```
You will most likely need environmental variable JAVA_HOME being permanently set. To do this we will need to create new image committing
ENV variable
```
docker commit --change "ENV JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/" space-1 space-image:0.3
```
### Run applications permanently
If you want application to keep running after terminal is closed start it with **"&!"** at the end. For example, the application we started in the previous section (NodeJs) should be started like this
> ```npm-gui 0.0.0.0:19011 &!```
Now, if you disconnect from the workspace and close terminal, the application will still continue running in the workspace, untill the workspace is fully stopped (look in the section "Stop workspace").
If you want application to run permanently all the time, ewhen the workspace container restarted and even on all the new images
created from this workspace, use supervisord. [Read here how to create configuration file for supervisord](http://supervisord.org/configuration.html)
For example, in case we want to make npm-gui running permanently, create file with any name and extension **.conf** in the folder */etc/supervisord*
```
nano /etc/supervisord/npm-gui.conf
```
Paste the following
```
[program:npm-gui]
directory=/home/npmgui
command=/bin/sh -c " . env/bin/activate && npm-gui 0.0.0.0:19011 "
```
And create folder for logs
```
mkdir -p /home/log
```
Create new workspace image with all the changes
```
docker commit space-1 space-image:0.4
```
Stop currently running workspace
```
docker stop space-1
```
And run workspace from the newly-created image
```
docker run --name space-4 -d -p 19011:19011 space-image:0.4
```
## Create documentation
## Customize Workspace
### Customize Quickstart
Workspace can easily be customized for your specific needs. You can also use Workspace for a complex project, and might need a
tool to write remarks, plans, action plans. As well as architectural artefacts for the components you wish to implement. Often it is
@ -441,7 +674,6 @@ MkDocs project is located in the `/home/docs/` folder. It has subfolder called `
are stored. Simply create new `.md` file there. And add reference about this file to the MkDocs config `/home/docs/mkdocs.yml`. You will see that
the new page has appeared in your Workspace UI - it has live reload, and you dont need to do annything, just write in the markdown files.
<p align="center">
<img src="https://raw.githubusercontent.com/bluxmit/alnoda-workspaces/main/workspaces/python-workspace/img/workspace-docs.gif" alt="workspace-docs" width="900">
</p>