PKC Complete Installation Process
Introduction
This page is written to give complete documentation on how the PKC is installed, description of all the related services, and the concept behind the architecture design. PKC Architecture is implemented at several docker container that runs its own service on same virtual network. PKC can be installed on a Virtual Machine or Bare-Metal machine.
Docker Concept
Docker is an containerized application runs on top of host operating system. It is some form of more lightweight implementation of virtualization. All we need to do to deploy and shipped new application is to containerized all our executable code and all its dependencies inside one docker container, and we are ready to delivered the application.
- Docker is a tools, to develop and run container
- Container is the packed executable and application code.
In order to run container, we need some kind of tools, which in this case are using Docker. For further readings, please visit this page for comprehensive explanation of Docker by Bibin Wilson.[1]
Below is the simple diagram on how container is deployed into one's computer, to give better understanding on high-level concept of docker container.
On host Operating System, administrator only need to install and configured Docker or other software with the capability to run container, and installed all the application container within the operating system. Them all the service will be ready to go without need to install all the code and dependecies.
Ansible Concept
Ansible is open-source tools that provide automation tools for cross-platform computer support. Enabled developer or DevOps to perform various task of installation, configuration, and provisioning computer and/or server. Basically everything that system administrator does in routine. And it does not depend on any agent software nor additional security layers. So its easy to use and deploy. Below are the simple schematic diagram to better give high-level understanding of ansible.
The Ansile script, only need to be deployed on one ansible agent with connection to the servers. Then the task that has already defined in ansible agent will be executed on target computer and/or server.
PKC Architecture Review
Please find below are the diagram of PKC Implementation on micro-services and containerization.
PKC consist of below containers
- XLP_Mediawiki: Mediawiki service, this is where all the content of XLP can be accessed, and the entrypoint for the implementation.
- XLP_Gitea: Gitea service, for storing files and source-code.
- XLP_Keycloak: Identity service provider for managing users
- XLP_Matomo: Web Analytic Service, to monitor the usage and
- XLP_VS: Web-Based Visual Studio Code, to manage source-code.
- phpmyadmin: Tools for managing the databaser server.
- XLP_MariaDB: mySQL RDBMS Provider
- NGINX: Installed on host server, to manage the connectivity between incoming traffic and microservices.
All the binds folder is under the folder of $HOME/cs/mountpoint, below are the list of folder bind into containers
| Folder/Filename | Container | Container's Folder |
|---|---|---|
| backup_restore/mariadb | xlp_mariadb | /mnt/backup_restore/mariadb |
| backup_restore/mediawiki | xlp_mediawiki | /mnt/backup_restore/mediawiki |
| gitea | gitea | /data |
| images | xlp_mediawiki | /var/www/html/images |
| LocalSettings.php | xlp_mediawiki | /var/www/html/LocalSettings.php |
| mariadb | xlp_mariadb | /var/lib/mysql |
| matomo | xlp_matomo | /bitnami/matomo |
| vs | xlp_vs | /config |
| mysql-init | xlp_mariadb | /docker-entrypoint-initdb.d |
NGINX Configuration is stored on host folder /etc/nginx/sites-enabled, which forward traffic from outside into each container's port. below are the table of default PKC Configurations.
| Container | Port# | Subdomain | Remarks |
|---|---|---|---|
| xlp_mariadb | N/A | N/A | Not exposed |
| phpmyadmin | 32040 | pma | |
| xlp_keycloak | 32060 | kck | |
| xlp_matomo | 32010 | mtm | |
| xlp_mediawiki | 32001 | [Default] | |
| xlp_gitea | 32030 | git | |
| xlp_vs | 32050 | code |
Pre-Requisite
PKC can be installed on fresh-installation of Ubuntu Linux 20.08 or Ubuntu Linux 18.04 minimal server setup. There's no specific software that needs to be installed beforehand. However, there are several items that needs to be configured before we can start the ansible script to setup PKC
How to provision your server
Below are the items that need to be properly setup before we can run the ansible installation script.
DNS Configuration
To enable the https:/ protocols, you will need to setup or procure domain name to point to your server's or VM's Public IP. Below are the default and subdomain configuration to setup.
| Subdomain | |
|---|---|
| [default] / www | Your Public IP |
| pma | |
| kck | |
| mtm | |
| git | |
| code |
Provide Passwordless Access
To enable ssh passwordless access, you will need to enable the private key/public key method, this is required to run the automated ansible script. On some cloud provider such as AWS or Google Cloud, the only way to access the ssh is through public key/private key method. In such case, you can directly use the provided private key. To execute the process please refer to How to create passwordless access page.
Installation Execution
This section will provide the required step to install the PKC Infrastruction on your selected server. This process assuming that you already completed all the necessary pre-requisite above in advance.
Source Code
To clone the specific ansible script for this PKC installation, you need change to your chosen folde and clone git repository with branch [dev], with below command:
git clone -b dev https://github.com/xlp0/PKC.git
This command will create new folder called PKC inside the folder, then change to PKC folder by executing change folder command
cd PKC
There are two files that you will need to adjust, according to your installation target, first is .env file, first line is YOUR_DOMAIN,and second line is YOUR_EMAIL_ADDRESS.
# [P]ersonal [K]ownlegde [C]ontainer # PKC .env configuration files # # # Inform your domain here, keep at localhost for local implementation # YOUR_DOMAIN=[put your domain here] # Inform your transport methods, highly recommended to use HTTPS # DEFAULT_TRANSPORT=https # Email notification for Certbot Renewal YOUR_EMAIL_ADDRESS=[put your email address here] # # # Please DO NOT Change below configuration entry # unless you really know what you are doing # # Port Number for media wiki PORT_NUMBER=32001 # Port Number for matomo MATOMO_PORT_NUMBER=32010 # Port Number for PHP My Admin PHP_MA=32040 # Port Number for Gitea GITEA_PORT_NUMBER=32030 # Port Number for vs-code VS_PORT_NUMBER=32050 # VS Default password VS_PASSWORD=xlp-vs-pass # VS Sudo Password VS_SUDO_PASSWORD=xlp-vs-sudo # Keycloack Port Number KCK_PORT_NUMBER=32060
YOUR_DOMAIN is the target where PKC will be installed
YOUR_EMAIL_ADDRESS is the email address will be use for registering SSL Certbot.
Second file is the hosts file. In this file, you need to inform installer how to access the server, and the respecting private key location. Below are the format of the file
[your server IP Address or entry in ~/.ssh/config] ansible_connection=[type of connection] ansible_ssh_private_key_file=[complete folder location and filename for private key] ansible_user=[server's user] domain=[your domain name]
Below are the example of the file content, once adjustment has been made
my-domain.org ansible_connection=ssh ansible_ssh_private_key_file=~/.ssh/my-private-key ansible_user=myuser domain=my-domain.org