# Ansible-Terraform Workspace This workspace - is a "dockerized" development environment with [Ansible](https://docs.ansible.com/) and [Terraform](https://www.terraform.io/) and lots of other stuff installed, so that you don't need to do it yourself. Create infrastructures with Terraform, and configure it with Ansible. ``` docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/ansible-terraform-workspace ``` and open [localhost:8020](http://localhost:8020) in browser ## Contents * [About](#about) * [Use-cases](#use-cases) * [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) ## About The workspace contains browser-based Visual Studio Code, and other browser-based tools that make it comfortable working with dockerized environments. [GIF] Workspace has the following Ansible tools installed: - [**Ansible Ara**](https://github.com/ansible-community/ara). Configured to track execution of all ansible playbooks, has UI. - [**Ansible-pre-commit**](https://github.com/adarnimrod/ansible-pre-commit) - [**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 Mitogen**](https://mitogen.networkgenomics.com/ansible_detailed.html) - [**Ansible Doctor**](https://ansible-doctor.geekdocs.de/) Workspace has the following Terraform tools installed: - [**Pre-commit-terraform**](https://github.com/antonbabenko/pre-commit-terraform) - [**Blast-Radius**](https://github.com/28mm/blast-radius). Has UI, visualizes any terraform project in folder /home/terraform/. - [**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 has the following common tools installed: - **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. - [**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. ## Use-cases There are several reasons to use this workspace. 1) Convenience. The first and obvious reason to use this workspace - is to 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 have 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.
3) Workspace makes collaboration easier. Both Ansible and Terraform can be used from a developer's local machine. It is convenient for personal use, but when it comes to collaborations, things become complicated: everyone needs to have the same versions of tools and dependencies. Workspace can be used and shared "as a whole", removing this difficulty. 4) 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. ## 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/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. ### Workspace terminal 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
*(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 Ubuntu terminal now. Execute the followinng command to know your workspace user > `whoami` ### Multiple workspaces Every workspace requires range of ports. If one workspace is up and running, the ports 8020-8035 are taken. Ansible-terraform workspace itself uses 11 ports (8020-8030), 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/ansible-terraform 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-8035". 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/ansible-terraform-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/ansible-terraform-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-8035:8020-8035 -v /var/run/docker.sock:/var/run/docker.sock alnoda/ansible-terraform-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 workkspace requires only 3 steps: - get virtual server on your favourite cloud (Digital Ocean, Linode, AWS, GC, Azure ...) - [install docker](https://docs.docker.com/engine/install/) on this server - ssh to the remote server and start workspace ``` docker run --name space-1 -d -p 8020-8035:8020-8035 -e WRK_HOST="