diff --git a/README.md b/README.md index 2d641d7..7ca729c 100644 --- a/README.md +++ b/README.md @@ -185,7 +185,7 @@ The most general workspace - is [`Ubuntu-workspace`](./workspaces/ubuntu-workspa in order to run multiple processes, adds cron, zsh, and other applications that will be used in most workspaces. Other general workspaces are the [`Base-Workspace`](./workspaces/base-workspace/README.md), which adds several browser-based applications, -like task scheduler, file browser, documentation framework and workspace own page. [`Workspace-in-docker`](./workspaces/workspace-in-docker/README.md) +like task scheduler, file browser, documentation framework and workspace own UI. [`Workspace-in-docker`](./workspaces/workspace-in-docker/README.md) adds [Eclipse Theia](https://theia-ide.org/) to the Base-Workspace. Theia - is an open-source browser-based VS-Code version, making Workspace-in-docker to be a general base workspace, to be used in order to create workspaces for specific tasks (like Python workspace, or Ansible workspace). diff --git a/workspaces/codeserver-workspace/README.md b/workspaces/codeserver-workspace/README.md index bfe1ade..eeed3fd 100644 --- a/workspaces/codeserver-workspace/README.md +++ b/workspaces/codeserver-workspace/README.md @@ -4,7 +4,7 @@ General-purpose dockerized workspace - an environment fully isolated inside a do to file or restored, pushed to docker registry, started on a cloud server.

- Collage + Collage

#### Try it out @@ -46,7 +46,7 @@ The Workspace contains browser-based Visual Studio Code, and several browser-bas

- WID demo + WID demo

**Tools with UI** @@ -91,7 +91,7 @@ The IDE is already configured to make code highlighting for many programming lan

- Code-server demo + Code-server demo

@@ -217,7 +217,7 @@ Open [localhost:8020](http://localhost:8020), and from there open other applicat

- codeserver-ui.png + codeserver-ui.png

The rest of the ports from the port range can be used in order to expose optional applications, or applications you might @@ -298,7 +298,7 @@ use utility `/home/abc/utils/remote.py` to generate create docker-compose projec 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:

- generate-remote.gif + generate-remote.gif

. Copy this folder to the remote server where you want to launch the Python workspace. @@ -594,7 +594,7 @@ the new page has appeared in your Workspace UI - it has live reload, and you don

- workspace-docs + workspace-docs

You can easily build beautiful static website from this documentation diff --git a/workspaces/mkdocs-magicspace/README.md b/workspaces/mkdocs-magicspace/README.md index 7cd7507..15af998 100644 --- a/workspaces/mkdocs-magicspace/README.md +++ b/workspaces/mkdocs-magicspace/README.md @@ -5,27 +5,33 @@ MkDocs-MagicSpace is an all-in-one tool, carefully crafted to make the development of gorgeous documentation websites like [**this one**](https://mkdocs-magicspace.alnoda.org/) as easy as possible. +

+ Collage +

+ + Try it out: ``` docker run --name space-1 -d -p 8020-8035:8020-8035 alnoda/mkdocs-magicspace ``` -and open [http://localhost:8020] in browser +and open [localhost:8020](http://localhost:8020) in browser ## Contents +* [Why documentation websites with MkDocs](#why-documentation-websites-with-mkdocs) +* [About](#about) +* [MkDocs features](#mkdocs-features) * [Use-cases](#use-cases) -* [Why documentation websites](#why-documentation-websites) -* [Features](#features) -* [The technology behind](#the-technology-behind) * [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) +* [Use Workspace](#use-workspace) + * [Create MkDocs website](#create-mkdocs-website) * [Install applications](#install-applications) * [Schedule jobs with Cron](#schedule-jobs-with-cron) * [Python](#python) @@ -39,30 +45,9 @@ and open [http://localhost:8020] in browser * [Move workspace to the cloud](#move-workspace-to-the-cloud) -## Use-cases +## Why documentation websites with MkDocs -With the help of MkDocs-MagicSpace you can develop, build and serve the following kinds of websites: - -1. Awesome looking docs for your open-source project. Use HTML & CSS to create front page and markdown for doc pages. - -2. User manuals and API docs. While enterprise docs are for internal use, create great-looking API websites for your users, and manuals for your customers. - -1. Enterprise documentation websites that unite numerous git repositories into one documentation project. - -4. Tutorials and training websites. Do you have a lot of experience in something? Share it with the world. -MkDocs-MagicSpace helps you to highlight the code in many programming languages, write complex mathematical formulas, -[draw diagrams]((https://mermaid-js.github.io/mermaid/#/)) and so much more! - -5. With MkDocs-MagicSpace you can also create books, booklets, and brochures as .pdf files. - -One of the most convenient features of the MkDocs-MagicSpace - is that it is a workspace in docker. -You use it on your local machine, you can run it on the remote server and collaborate with your colleagues, -you can give it to your peer as a whole. And you can use it to serve your docs from any server, no matter -if it is public or inside the company's VPN. - -## Why documentation websites - -*Why create separate documentation websites? Why not just write Git readme files?* +*Why create separate documentation websites? And if so, why MkDocs?* - MkDocs website with beautiful themes looks much better than any readme file. The resulting documentation website looks professional and awesome. - MkDocs adds text search to your documentation website. @@ -72,22 +57,18 @@ if it is public or inside the company's VPN. can create a unified documentation website from multiple repositories in Github, GitLab, Bitbucket. - You can add such features as Google Analytics, multi-language localization. -*And what about Confluent?* -The approach of having docs in different places (Git repositories, Confluent, Wiki, etc.) has serious drawbacks. It creates chaos, and documentation inevitably diverges with time. -And you never know where to look for the information you need. +## About -The best docs live together with the code. With MkDocs-MagicSpace you can follow this practice with ease, build a documentation website -from one or many git repositories, include readme files that live close to the code. You can have a build process that even creates -auto-documentation directly from the code. +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. -## Features +
+ Demo: MkDocs-MagicSpace +
-MkDocs-MagicSpace has [**MkDocs**](https://squidfunk.github.io/mkdocs-material/) installed with a collection of extensions and plugins -that bring MkDocs to the next level. - -MkDocs-MagicSpace is an extension of the [workspace-in-docker](https://github.com/Alnoda/workspaces-in-docker/blob/main/workspaces/workspace-in-docker/README.md) -and has all its features: +

+ Magicspace demo +

- **Workspace UI** - launch all workspace tools from one place. - [**Eclipse Theia**](https://theia-ide.org/docs/) - open source version of popular Visual Studio Code IDE. Theia is trully open-source, has @@ -99,10 +80,23 @@ VS-Code extensions and works in browser. This means it can run inside a docker c - [**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. -Built on top of Base-workspace and Ubuntu-workspace, this workspace gets all the features those workspaces have. -In particular, workspace-in-docker provides excellent experience when working directly in the terminal, and has docker-in-docker. +**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 -#### The technology behind +Built on top of [Workspace-in-docker](https://github.com/Alnoda/workspaces-in-docker/blob/main/workspaces/workspace-in-docker/README.md), +[Base-workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/base-workspace/README.md), and +[Ubuntu-workspace](https://github.com/bluxmit/alnoda-workspaces/blob/main/workspaces/ubuntu-workspace/README.md), +this workspace gets all the features those workspaces have. + +#### MkDocs features MkDocs-MagicSpace in its essense is all about [**MkDocs**](https://www.mkdocs.org/) - a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. @@ -125,6 +119,29 @@ MkDocs-MagicSpace has lots of packages and extensions already installed: **(The complete list of installed packages - /home/abc/installed-python-packages/mkdocs-requirements.txt)** +## Use-cases + +This workspace has many tools and dependencies, configuring it from scratch will cost you a lot of time. + +With the help of MkDocs-MagicSpace you can develop, build and serve the following kinds of websites: + +1. Awesome looking docs for your open-source project. Use HTML & CSS to create front page and markdown for doc pages. + +2. User manuals and API docs. While enterprise docs are for internal use, create great-looking API websites for your users, and manuals for your customers. + +1. Enterprise documentation websites that unite numerous git repositories into one documentation project. + +4. Tutorials and training websites. Do you have a lot of experience in something? Share it with the world. +MkDocs-MagicSpace helps you to highlight the code in many programming languages, write complex mathematical formulas, +[draw diagrams]((https://mermaid-js.github.io/mermaid/#/)) and so much more! + +5. With MkDocs-MagicSpace you can also create books, booklets, and brochures as .pdf files. + +One of the most convenient features of the MkDocs-MagicSpace - is that it is a workspace in docker. +You use it on your local machine, you can run it on the remote server and collaborate with your colleagues, +you can give it to your peer as a whole. And you can use it to serve your docs from any server, no matter +if it is public or inside the company's VPN. + ## Launch Workspace Workspaces - are merely docker containers, that's why managing workspaces is easy and intuitive - it is enough to know only docker commands, @@ -277,25 +294,67 @@ use utility `/home/abc/utils/remote.py` to generate create docker-compose projec > `python /home/abc/utils/remote.py --workspace="mkdocs-magicspace" --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. +**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`. +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: + +

+ mkdocs-remote.gif +

+ +. 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. +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 + +

+ accept-risk +

+ +After you accept the risk, authentication window will appear asking you the user and password, that you have set as, + +

+ auth +

+ ## Use Workspace -Among the common actions you'd do in the workspace are +### Create MkDocs website + +[MkDocs](https://www.mkdocs.org/) is very powerful. Even more powerful it becomes with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). +But this workspace takes it to the space by having tons of Markdown plugins carefully selected, configured, and set up. It would be impossible to +demonstrate all of the advanced Markdown features in the Readme file, simply because standard engines that render Markdown do not support the +advanced features. + +We have prepared extended Markdown tutorials, so that you don't need to search in the Internet for docs of every Markdown plugin. +They are all in one place: + +* [Intro](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/intro/) +* [Basics](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/basics/) +* [Hack the markdown](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/hack-markdown/) +* [Improve readability with tabs, lists and footnotes](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/improve-readability/) +* [Create tables](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/tables/) +* [Highlight with blockquotes and admonitions](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/highlight-what-matters/) +* [Make it classy with emoji, icons and more](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/classy-markdown/) +* [Make images awesome](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/images/) +* [Add the code](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/add-the-code/) +* [Write formulas](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/formulas/) +* [Draw diagrams](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/diagrams/) +* [Use templates](https://mkdocs-magicspace.alnoda.org/tutorials/markdown/templates-macros/) + +In addition you can find here tutorials how to build and deploy your website in just couple of clicks +* [Build website](https://mkdocs-magicspace.alnoda.org/tutorials/get-online/build-workspace/) +* [Publish on GitHub Pages](https://mkdocs-magicspace.alnoda.org/tutorials/get-online/github-pages/) + -- 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 diff --git a/workspaces/mkdocs-magicspace/img/mkdocs-collage.png b/workspaces/mkdocs-magicspace/img/mkdocs-collage.png new file mode 100644 index 0000000..bc3ec5f Binary files /dev/null and b/workspaces/mkdocs-magicspace/img/mkdocs-collage.png differ diff --git a/workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif b/workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif new file mode 100644 index 0000000..7347799 Binary files /dev/null and b/workspaces/mkdocs-magicspace/img/mkdocs-magicspace-demo.gif differ diff --git a/workspaces/mkdocs-magicspace/img/mkdocs-remote.gif b/workspaces/mkdocs-magicspace/img/mkdocs-remote.gif new file mode 100644 index 0000000..2ba1153 Binary files /dev/null and b/workspaces/mkdocs-magicspace/img/mkdocs-remote.gif differ