diff --git a/build.py b/build.py index 16858ba..a6b827e 100644 --- a/build.py +++ b/build.py @@ -1,7 +1,5 @@ import subprocess -import tomlkit as toml - from scripts_config import readme_files # type: ignore def create_readme(): diff --git a/docs/getting_started/accessing_the_server.md b/docs/getting_started/accessing_the_server.md new file mode 100644 index 0000000..fe90401 --- /dev/null +++ b/docs/getting_started/accessing_the_server.md @@ -0,0 +1,2 @@ +# Accessing the Server +

Currently, the server will be accessible only to researchers within the I-Form research group via extremely localised intranet. As development continues, the server will be made available across the wider internal intranet and eventually externally via the internet. To access the server please request access from the server administrator.

\ No newline at end of file diff --git a/docs/getting_started/cockpit.png b/docs/getting_started/cockpit.png new file mode 100644 index 0000000..b1d5313 Binary files /dev/null and b/docs/getting_started/cockpit.png differ diff --git a/docs/getting_started/deploying_new_nodes.md b/docs/getting_started/deploying_new_nodes.md new file mode 100644 index 0000000..1565877 --- /dev/null +++ b/docs/getting_started/deploying_new_nodes.md @@ -0,0 +1,48 @@ +# Deploying New Nodes +The deployment of new nodes can be achieved in several ways. To maintain maximum flexibility, these methods range from extremely user friendly methods to more complex methods that require a greater degree of technical knowledge. The following sections will describe the various methods available for deploying new nodes. + +## Using the Node Deployer GUI +The node deployer GUI is a simple, user friendly tool that allows the user to deploy new nodes to the server with minimal technical knowledge. This tool is available at the [node deployer repository](https://github.com/Cian-H/I-Form_Server_Node_Deployer).
+![The node deployer GUI](node_deployer_gui.png)
+As long as the user has the correct IP address for the switch, and the correct swarm token, this tool will automatically create an ignition drive that will automatically configure the new node to join the server cluster. The user will also need to [https://get.opensuse.org/leapmicro/5.5/](create an OpenSUSE Leap Micro) install USB using the "Self-Install" image. To deploy the node, the user will then need to insert both USB drives into the new node and boot from the OpenSUSE USB. By following the on screen instructions, the node will be automatically configured and added to the cluster. + +## Using the Node Deployer CLI +For more advanced users, the node deployer CLI can be used to deploy new nodes. This tool is available at the [node deployer repository](https://github.com/Cian-H/I-Form_Server_Node_Deployer). +

+![The node deployer CLI](node_deployer_cli.png) +

+Similar to the GUI, this tool can automatically create an ignition drive that will automatically configure the new node to join the server cluster. Again, the user will also need to [https://get.opensuse.org/leapmicro/5.5/](create an OpenSUSE Leap Micro) install USB using the "Self-Install" image. This can be achieved using a tool such as [Etcher](https://www.balena.io/etcher/). To deploy the node, the user will then need to insert both USB drives into the new node and boot from the OpenSUSE USB. By following the on screen instructions, the node will be automatically configured and added to the cluster. An ignition drive can be created using the following command: +``` bash +node_deployer create-ignition-disk -d -ip -t +``` +This tool can also be used to create .img files that can be flashed to the node's internal storage. This is useful for nodes that do not have USB ports or for other purposes such as constructing containerised nodes. To create an image file, the following command can be used: +``` bash +node_deployer create-img -o -ip -t +``` +The user can then flash this image to the node's internal storage using a tool such as [Etcher](https://www.balena.io/etcher/).
+Finally, the node deployer CLI can also be used to create an image from a JSON configuration file. This is useful as a means of saving deployment configurations for easy use in the future, or to deploy configurations built using other server configuration tools such as the [https://opensuse.github.io/fuel-ignition/](fuel-ignition) deployer. To achieve this, the following command can be used: +``` bash +node_deployer json-to-img -i -o +``` +Further documentation on the node deployer CLI can be found at the [node deployer documentation site](https://i-form-node-deployer.netlify.app/commands/) + +## Using the Node Deployer API +In addition to the dedicated applications, the node deployer can also be used as a library. This allows the user to integrate the node deployer into their own applications. For example, to achieve the same result as the GUI, the following code could be used: +``` python +from node_deployer import create_ignition_disk + +create_ignition_disk( + disk="/dev/sdb", + password="password", + switch_ip="192.168.1.1", + swarm_token="EXAMPLE_SWARM_TOKEN" +) +``` +This code will create an ignition drive at /dev/sdb that will automatically configure the new node to join the swarm managed by the switch at the IP 192.168.1.1. Further documentation regarding this library is available at the deployer's [documentation site](https://i-form-node-deployer.netlify.app/). + +## Requirements +All of the above methods require the user to have the following: +- Python 3.12 or greater +- The node deployer software +- Docker +- An OpenSUSE Leap Micro install USB \ No newline at end of file diff --git a/docs/getting_started/node_deployer_cli.png b/docs/getting_started/node_deployer_cli.png new file mode 100644 index 0000000..88a8c23 Binary files /dev/null and b/docs/getting_started/node_deployer_cli.png differ diff --git a/docs/getting_started/node_deployer_gui.png b/docs/getting_started/node_deployer_gui.png new file mode 100644 index 0000000..fd38475 Binary files /dev/null and b/docs/getting_started/node_deployer_gui.png differ diff --git a/docs/getting_started/podman.png b/docs/getting_started/podman.png new file mode 100644 index 0000000..184999d Binary files /dev/null and b/docs/getting_started/podman.png differ diff --git a/docs/getting_started/terminal.png b/docs/getting_started/terminal.png new file mode 100644 index 0000000..6e7f979 Binary files /dev/null and b/docs/getting_started/terminal.png differ diff --git a/docs/getting_started/usage.md b/docs/getting_started/usage.md new file mode 100644 index 0000000..3ae76d5 --- /dev/null +++ b/docs/getting_started/usage.md @@ -0,0 +1,18 @@ +# Usage +## Server Management +Once the server has been accessed, the user will be presented with a login screen. Once logged in, the user will be presented with a dashboard from which the server can be managed. This dashboard is provided via the [cockpit project](https://cockpit-project.org) and from here it is possible to manage all functions of the server. Via the dropdown in the top left, the user can immediately connect to any node in the cluster. For each node, the system options and tools will then allow the user to interact with the nodes in the server. Management of the overall cluster is facilitated through interactions with any of the central switch nodes.
+![An example of a cockpit page](cockpit.png) + +

+ +## Deploying Applications +New docker containers can be deployed to the server node using the "Podman containers" tab of the cockpit UI. This page provides a list of all currently running containers, as well as a list of all available containers. Docker containers are deployed by contructing from images. To deploy a new container, simply click the "Get new image" button, and search for the container image you wish to deploy. Once the image has been downloaded, click the "run" button and set the configuration for building the container. At this point, the container will be built and deployed automatically.
+![The podman containers page](podman.png)
+**NOTE: This method will only deploy the container on a single node. Deployment to the cluster is currently implemented via portainer and documentation for this will be added soon.** + +
+ +## Accessing the terminal +By clicking the "Terminal" tab the user can directly interact with the selected node via a terminal. Through this terminal, all available installed programs can be executed and the user can interact with the server as if they were directly connected to it. This is particularly useful for debugging and troubleshooting issues with the server.
+![The terminal page](terminal.png)
+Here, the system can be managed, software can be updated (this can also be achieved via the "Software Updates" tab), and new native software can be installed (although, this should be avoided without good reason). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 7ec0033..d30c398 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,17 @@ -# Research Server Documentation +## Welcome +Welcome to the documentation for the I-Form Research Server. This documentation is intended as a user guide for researchers who wish to use, maintain, and otherwise interact with the server. Currently, the server is still undergoing deployment and testing, and as such, this documentation is a work in progress. If you have any questions, please contact the server administrator1. -[link_test](https://i-form-node-deployer.netlify.app) \ No newline at end of file +
+ +## Overview +The I-Form Research Server is intended to provide an adaptable, scalable, and secure platform from which to host research applications, tools, and services. The server architecture provides an extremely stable core operating system, with a flexible and adaptable containerised application layer. This makes it possible to quickly and easily add new software to our own cloud system without the need to worry about the various complexities of configuring and maintaining a server for each application. Research software often has very specific, unique requirements and must be updated or replaced frequently. For a traditional server, this can be a significant challenge. By providing a flexible, stable foundation that avoids this problem, this system should allow researchers to focus on their research, rather than maintaining research infrastructure. + +
+ +## Technical Details +The I-Form Research Server is constructed as an on top of a minimal [OpenSUSE Leap Micro](https://get.opensuse.org/leapmicro/5.5/) operating system. This provides a stable, immutable core operating system that is designed to be extremely secure and stable. On top of this, we use [Docker](https://www.docker.com) to provide a containerised application layer. The combination of these tools allows us to build a server using almost any hardware that may be available, linking them together into a compute cluster. This allows us to scale the server as needed, adding more compute power as required. + +

+ +## Footnotes +

[1]: email the server administrator

\ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index fc56ab5..0000000 --- a/docs/usage.md +++ /dev/null @@ -1 +0,0 @@ -# Usage \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml index c6ae7fb..58c0880 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -24,11 +24,15 @@ theme: toggle: icon: material/lightbulb-outline name: Switch to light mode + features: + - content.code.copy nav: - Home: index.md - Getting Started: - - Usage: usage.md + - Accessing the server: getting_started/accessing_the_server.md + - Usage: getting_started/usage.md + - Deploying new nodes: getting_started/deploying_new_nodes.md - Reference: # - FAQ: faq.md # - Troubleshooting: troubleshooting.md @@ -39,6 +43,15 @@ extra: version: provider: mike +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + plugins: #TODO: Add plugins, they seem to be broken at the moment # - material/optimize @@ -46,5 +59,6 @@ plugins: # - material/projects # - material/typeset - search - # - git-revision-date-localized: - # enable_creation_date: true \ No newline at end of file + - git-revision-date-localized: + enable_creation_date: true + - glightbox \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 17162ef..89cbcd3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,6 +11,8 @@ python = ">=3.8,<4.0" mkdocs = "^1.5.3" mkdocs-material = "^9.4.8" tomlkit = "^0.12.2" +mkdocs-git-revision-date-localized-plugin = "^1.2.1" +mkdocs-glightbox = "^0.3.4" [tool.poetry.scripts] build = "build:main"