diff --git a/docs/10_Get_started/10_Installation_on_a_server.md b/docs/10_Get_started/10_Installation_on_a_server.md index a5e941dab30672f20f604dc11d82eb7091d2ed6e..c160f32b620ccba2686a08d8452cbf0e7271e50c 100644 --- a/docs/10_Get_started/10_Installation_on_a_server.md +++ b/docs/10_Get_started/10_Installation_on_a_server.md @@ -1,8 +1,8 @@ -# Installation of CISERVER # +# Installation of CISERVER You can install the CISERVER on your own host. You need full access to the system - it won't run on a shared hosting. -## Apache Httpd + PHP ## +## Apache Httpd + PHP Install an Apache httpd and enablethese modules. @@ -10,17 +10,17 @@ Install an Apache httpd and enablethese modules. - proxy + proxy_fcgi (or proxy_http) for a proxy - socache_shmcb (on Debian for ssl connections) -For PHP 8.1 we need these packages +For PHP 8.x we need these packages - php-fpm - php-curl - php-intl - php-mbstring -- php-ldap +- php-ldap (for ldap authentication) - php-sqlite3 - php-xml -## Other required tools ## +## Other required tools These commandline tools must be installed. @@ -28,9 +28,9 @@ These commandline tools must be installed. - rsync - git -## Get sources ## +## Get sources -Extract the repository in `/var/www/ciserver.example.org`. +Extract the repository in `/var/www/ciserver.example.org`. You can download the archive from the git repository or use `git clone`. ```txt @@ -41,7 +41,7 @@ mv imldeployment ciserver.example.com The directory `/var/www/ciserver.example.com` is called approot in further documentation. -## Update virtual host config ## +## Update virtual host config Set the document root to the subdir `public_html`. We need two rewrite rules to redirect requests. @@ -70,7 +70,7 @@ In `[approot]/config/` copy the 2 *.dist files to the same filename but without ## Create data structure and tmp -The aplication works with +The aplication works with - a data directory /var/imldeployment - a tmp directory /var/tmp/imldeployment @@ -104,7 +104,7 @@ If you use ansible you can use this snippet. - '/var/imldeployment/packages/_files' ``` -## Enable shell for Apache service user ## +## Enable shell for Apache service user The service user of the webservice needs to execute commands with php function exec. By default this user has set nologin as shell - this muust be changed to `bin/bash`. diff --git a/docs/10_Get_started/20_Installation_with_Docker.md b/docs/10_Get_started/20_Installation_with_Docker.md index 5633cd4b69baaad29201ec990558a836879ad896..8ced80c07fd13ba9b91c0f7db4c77a7782800c88 100644 --- a/docs/10_Get_started/20_Installation_with_Docker.md +++ b/docs/10_Get_started/20_Installation_with_Docker.md @@ -1,8 +1,8 @@ -# Installation with a local Docker service # +# Installation with a local Docker service For development a docker environment is part of the repository data. -## Requirements ## +## Requirements * Linux system * a running rootless Docker service @@ -10,11 +10,11 @@ For development a docker environment is part of the repository data. * Git * Docker-compose * facl to set ACL for write permissions for your user and the webservice of the container -* sudo permssions +* sudo permssions * to set ACL permissions with setfacl * to remove tmp data -## Get Sources ## +## Get Sources As your local user execute the following steps: @@ -24,7 +24,19 @@ git https://git-repo.iml.unibe.ch/iml-open-source/imldeployment.git cd imldeployment ``` -## Set permissions ## +## Prepare and bring up container + +### Quick method + +Set permissions, update templates and start the container: + +```shell +./docker/init.sh i t u q +``` + +OR do in step by step like described in the chapters below. + +### Set permissions In the folder `docker` are all configurations and helpers to run a docker container. In it is an `init.sh` to set environment. @@ -53,7 +65,7 @@ You get a menu. select > ``` -Then press `i` and `Return` to set permissions. +Then press `i` and `Return` to set permissions. This sets the acl permissions for the subdirs @@ -85,14 +97,14 @@ You will see something like that: + set +vx ``` -## Start container ## +### Start container Then press `u` and `Return` to run `docker-compuse up`. On the 1st run it needs to download the PHP docker image with Apache httpd and takes a few more seconds. If ist is up you can run <http://localhost:8002/> in your webbrowser. -## Change port ## +## Change port If you need to change the port then stop a running container. Edit `docker/init.sh.cfg` and set a new port @@ -107,8 +119,10 @@ APP_PORT=8002 After any change in init.sh.cfg we update the configs with ```shell -./docker/init.sh +./docker/init.sh t u q ``` Then press `t` (generate files from templates) + `Return`. If you start the container again the application is available under the new port. + +The key `u` brings up the container. \ No newline at end of file diff --git a/docs/10_Get_started/30_Filestructure.md b/docs/10_Get_started/30_Filestructure.md index 14a7be05cd8f16e639c9926424d8247cccbf4557..756107f978c7e9f8c5a50c8048e9a39939c9baf3 100644 --- a/docs/10_Get_started/30_Filestructure.md +++ b/docs/10_Get_started/30_Filestructure.md @@ -1,10 +1,10 @@ -# File structure # +# File structure * web - ui and api * data dir - configuration, database, built archives * temp area - checked out projects to read comit messages -## Approot and website ## +## Approot and website Default: /var/www/[YOUR-DOMAIN]/public_html/ @@ -59,7 +59,7 @@ Default: /var/www/[YOUR-DOMAIN]/public_html/ └── webservice ``` -## Data ## +## Data By default: /var/imldeployment @@ -75,6 +75,6 @@ imldeployment/ └── _files ``` -## Temp ## +## Temp By default: /var/tmp/imldeployment diff --git a/docs/10_Get_started/40_Dependencies.md b/docs/10_Get_started/40_Dependencies.md index b07292685e6a5c9a8003078e4c6a15fc05dea97e..446e491a77ff3120f0e9e1a541e6dc277a5be4fd 100644 --- a/docs/10_Get_started/40_Dependencies.md +++ b/docs/10_Get_started/40_Dependencies.md @@ -1,5 +1,5 @@ -# Dependencies # +# Dependencies Related Components of the CI server diff --git a/docs/20_Configuration/10_Configuration.md b/docs/20_Configuration/10_Configuration.md index eb241ef4a1ada675073d6bc0960d1685e41a6837..2044df2700deb6c2f83bb548f5c3a3361d8285a2 100644 --- a/docs/20_Configuration/10_Configuration.md +++ b/docs/20_Configuration/10_Configuration.md @@ -4,4 +4,3 @@ The configuration is a combination of * config/config_defaults.php - containing shipped defaults (do not edit) * config/config_custom.php - for your overrides of all default settings - diff --git a/docs/30_Server/Processes/10_Build.md b/docs/30_Server/Processes/10_Build.md index 71885d8a1c7cd92a61f81731ab96ef8dd2e0e258..492260d2382e21cbea5ee872e54f6e3952f906d6 100644 --- a/docs/30_Server/Processes/10_Build.md +++ b/docs/30_Server/Processes/10_Build.md @@ -1,4 +1,4 @@ -# Build # +# Build A build process can be started ... @@ -10,25 +10,25 @@ Among its steps are some builtin, some depend on the project settings and some c A build is denied if a project has no activated phase the project settings. -## Overview ## +## Overview  -## Steps ## +## Steps -### Create working directory ### +### Create working directory Outdated kept builds will be cleaned up. Below `/var/imldeployment/build/` a subdirectory with the id of the project will be created. In that one a uniq directory will be created by using a timestamp. -### Get sources ### +### Get sources The `git clone` fetches the sources from the Git repository Remark: at the moment ony Git is suported as version control system. An interface in the classes subdir describes the required method to be implemented. An additional VCS will be available in the project settings if it was added. -### Project specific actions ### +### Project specific actions An `chmod 755 /hooks/on*` makes hook scripts executable. @@ -43,7 +43,7 @@ Recommendation: Use a script named `hooks/onbuild` and put your project specisif actions into it. Read the next chapters to use given environment and scripts. -#### Custom vars #### +#### Custom vars A file named `ci-custom-vars` will be created containing the given data in the project config. Its idea is to be sourced by hook script to set variables in the current shell. @@ -64,7 +64,7 @@ cd .. echo myVar=$myVar ``` -#### Builtin environment #### +#### Builtin environment * $GIT_SSH - full path to git ssh wrapper (CI-Root/shellscripts/gitsshwrapper.sh) * $DIR_SSH_KEYS - full path to ssh keys (/var/imldeployment/data/sshkeys) @@ -103,11 +103,11 @@ Important: at the end of the hook script uninstall it by using `nvmremove`. * CI-Git-Repo .. nvm_init.sh: <https://git-repo.iml.unibe.ch/iml-open-source/imldeployment/-/blob/master/shellscripts/nvm_init.sh> * NVM: <https://github.com/nvm-sh/> -### Remove vcs data ### +### Remove vcs data The version control data (`.git` directory in build root) will be removed. -### Build or compress ### +### Build or compress (1) A metafile `[Projecd_ID].json` will be created in the build root. It will be used to identify the package or installation. It contains date, branch and commit message. @@ -124,17 +124,17 @@ The output dir is `/var/imldeployment/packages/_files/[Project_ID]/`. Here are s (3) If there are files in hooks/templates/ the will be copied into the package output directory. They can be used by automation tools like puppet to generate configuration files for different targets and different phases. -### Remove build dir ### +### Remove build dir If all actions were successful the buld directory will be deleted. -### Add in queue of 1st phase ### +### Add in queue of 1st phase A successful build triggers the queuing to the first active phase of this project. A phase can define deploy times to define, when a rollout is allowed. In the special case that the deploy time has no limit it will be installed instantly. Otherwise you will see the package in the queue column of a phase. -## If a build fails ## +## If a build fails The working directory will be kept. In the project config the number of kept projects is set (default: 3). Additionally old failed builds (older 7 days) will be deleted by a cronjob. diff --git a/docs/_index.md b/docs/_index.md index af3b8b0c1a21dbf6bc9c1c00cd16622454d92a01..f732e661de11a881b172881296df426480cbcaa1 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -1,4 +1,4 @@ -# CI Server # +# CI Server Free software and Open Source from University of Bern :: IML - Institute of Medical Education @@ -8,7 +8,7 @@ Free software and Open Source from University of Bern :: IML - Institute of Medi - - - -## Description ## +## Description CI node that checks out projects from git repositories and builds an deployable archive. The archives can be synched to multiple deployment targets e.g. puppet master or a protected software archive. @@ -40,7 +40,7 @@ This project is related to * CI package server <https://git-repo.iml.unibe.ch/iml-open-source/ci-pkg> * Deployment client written in bash <https://git-repo.iml.unibe.ch/iml-open-source/imldeployment-client> -## Features ## +## Features * checkout from git via SSH with multiple ssh keys (can be extended with a plugin) * build has hooks to customize build process @@ -54,7 +54,7 @@ This project is related to * sends messages (email, Slack) * API to start a build from somewhere, e.g. from a devops workplace or Gitlab server -## Screenshots ## +## Screenshots The overview over all projects is the starting page after login. It shows all projects and which build is rolled out to which phase. diff --git a/docs/images/screenshot_overview_all_projects.png b/docs/images/screenshot_overview_all_projects.png index 98814ed166811f01003a83a1900ae27501f4e41a..41555dba0b3d1703f2018f41af4dadc20afd904f 100644 Binary files a/docs/images/screenshot_overview_all_projects.png and b/docs/images/screenshot_overview_all_projects.png differ diff --git a/docs/images/screenshot_overview_project.png b/docs/images/screenshot_overview_project.png index 768a4e8743270214ae657f5d0db17ab7fd50482d..3441a1292451c7836f87788c7949f5ee4419198e 100644 Binary files a/docs/images/screenshot_overview_project.png and b/docs/images/screenshot_overview_project.png differ diff --git a/docs/style.css b/docs/style.css index 18463c799d9cd101d8f9b27a282128cde4494d99..45383c3288f17a74d88fc2ffca48307f794d4592 100644 --- a/docs/style.css +++ b/docs/style.css @@ -1,13 +1,14 @@ /* override css elements of daux.io blue theme - version 2022-11-30 + version 2023-11-10 */ :root { /* Axels Overrides */ - --color-text: #222; - --link-color: #822; - --brand-color: var(--color-secondary); + --color-text: #234; + --link-color: #228; + --brand-color: var(--color-text); --brand-background: var(--body-background); + --code-tag-border-color: #d8d8d8; --hr-color: none; --search-field-background: none; --search-field-border-color: none; @@ -24,29 +25,32 @@ --axel_brand-pre-background-hover: rgb(255, 0, 51); ; --axel_h1_header: none; - --axel_h1: #345; + --axel_h1: #111; --axel_h1-bg: none; --axel_h1-bottom: 3px solid none; - --axel_h2: #156; - --axel_h2-bg: #f8fafb; - --axel_h2-bottom: 2px solid #467; + --axel_h2: #222; + --axel_h2-bg: none; + --axel_h2-bottom: 0px solid #467; --axel_h2-hero-bottom: 2px solid #912; - --axel_h3: #278; - --axel_h3-bottom: 1px solid #ddd; + --axel_h3: #333; + --axel_h3-bottom: 0px solid #ddd; + --axel_h4: #444; --axel_hero_bg: #f8f8f8; + --axel_img-border: 2px dashed #ccc; --axel_nav-bg: #fcfcfc; --axel_nav-buttomborder: #ddd; --axel_pre-background: #f8f8f8; - --axel-th-background: #d0e0e8; + --axel-th-background: #e0e4e8; --axel-article-nav-border-top: 0px dotted #ddd; } .dark { /* Axels Overrides */ --color-text: #c0c0c0; - --link-color: #b44; + --link-color: #88e; --brand-color: var(--color-text); --brand-background: var(--body-background); + --body-background: #101418; --hr-color: none; --code-tag-background-color_: #bcc; --search-field-background: none; @@ -63,16 +67,17 @@ --axel_brand-pre-background-hover: rgb(255, 0, 51); ; --axel_h1_header: none; - --axel_h1: #777; + --axel_h1: #578; --axel_h1-bg: none; --axel_h1-bottom: none; --axel_h2: #467; - --axel_h2-bg: #202020; - --axel_h2-bottom: 2px solid #256; + --axel_h2-bg: none; + --axel_h2-bottom: 0px solid #256; --axel_h2-hero-bottom: 2px solid #712; --axel_h3: #589; - --axel_h3-bottom: 1px solid #333; + --axel_h3-bottom: 0px solid #333; --axel_hero_bg: #242424; + --axel_img-border: 2px dashed #555; --axel_nav-bg: #242424; --axel_nav-buttomborder: #555; --axel_pre-background: #bcc; @@ -133,7 +138,7 @@ a.Brand { .s-content h2 { background: var(--axel_h2-bg); color: var(--axel_h2); - font-size: 180%; + font-size: 190%; font-weight: bold; margin-top: 4em; border-bottom: var(--axel_h2-bottom); @@ -147,6 +152,12 @@ h2:first-of-type { margin-top: 0em; } +img{ + border: var(--axel_img-border); + border-radius: 1.5em; + padding: 0.7em; +} + .s-content h3 { background: var(--axel_h3-bg); color: var(--axel_h3); @@ -156,14 +167,26 @@ h2:first-of-type { border-bottom: var(--axel_h3-bottom); } -.s-content h4 { - margin: 0; - font-size: 100%; + +.s-content > h4 { + color: var(--axel_h4); + font-size: 135%; + font-weight: bold; + margin: 2em 0; +} + +.s-content .TableOfContentsContainer h4 { + margin: 1em 0; + font-size: 110%; text-align: center; - background-color: rgba(0, 0, 0, 0.05); + background-color: rgba(0, 0, 0, 0.1); padding: 0.3em; + font-weight: bold; + font-family: Arial; +} +ul.TableOfContents a{ + color: var(--color-text); } - .s-content pre { background: var(--axel_pre-background); } @@ -264,4 +287,4 @@ ul.TableOfContents ul { .Links a[href^="https://os-docs.iml.unibe.ch"]::before { content: '📗 '; -} \ No newline at end of file +} diff --git a/readme.md b/readme.md index 68c0f769607e2dc7252353f05c61f433bd1e7a06..5c3c0b2adffad8cc21b1cc9844776dfad4717f43 100644 --- a/readme.md +++ b/readme.md @@ -1,24 +1,24 @@ -# CI Server # +# CI Server Free software and Open Source from University of Bern :: IML - Institute of Medical Education 📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/imldeployment> \ 📜 License: GNU GPL 3.0 \ -📖 Docs: <https://os-docs.iml.unibe.ch/imldeployment/> +📗 Docs: <https://os-docs.iml.unibe.ch/imldeployment/> - - - -## Description ## +## Description CI node that checks out projects from git repositories and builds an deployable archive. The archives can be synched to multiple deployment targets e.g. puppet master or a protected software archive. -## Related projects ## +## Related projects * CI package server <https://git-repo.iml.unibe.ch/iml-open-source/ci-pkg> * Deployment client written in bash <https://git-repo.iml.unibe.ch/iml-open-source/imldeployment-client> -## Features ## +## Features * API to start a build from somewhere, e.g. from a devops workplace or Gitlab server * checkout from git via SSH with multiple ssh keys (can be extended with a plugin) @@ -32,7 +32,7 @@ The archives can be synched to multiple deployment targets e.g. puppet master or * receives install status * sends messages (email, Slack) -## Screenshot ## +## Screenshot The overview over all projects is the starting page after login. It shows all projects and which build is rolled out to which phase.