From b083cdfdc87b14b0cd3dd11c9a0f80c8375798d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Roman=20Dvo=C5=99=C3=A1k?= <xdvora19@fi.muni.cz>
Date: Fri, 27 Sep 2024 11:56:17 +0200
Subject: [PATCH] * minor changes in uppercase letters and wording and naming
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* change definition for testing
* fix formating and naming
* Apply 2 suggestion(s) to 2 file(s)
Co-authored-by: VĂt Baisa <xbaisa@fi.muni.cz>
* fix minor issues
* fix pipeline
* fox pipeline
* add old installation path to redirects
* fix old tech part overview
* add installation guide from new source
* add new submodule for deployment
---
.gitignore | 7 ++-
.gitlab-ci.yml | 9 +---
.gitmodules | 3 ++
docker-deployment | 1 +
docs/index.md | 4 +-
docs/tech/installation/INSTALLATION.md | 23 ++++++++
docs/tech/installation/back-README.md | 54 -------------------
docs/tech/installation/front-README.md | 21 --------
.../overview.md} | 16 ++----
docs/tech/tech_overview.md | 4 +-
mkdocs.yml | 10 +++-
utilities.sh | 9 ++++
12 files changed, 60 insertions(+), 101 deletions(-)
create mode 160000 docker-deployment
create mode 100644 docs/tech/installation/INSTALLATION.md
delete mode 100644 docs/tech/installation/back-README.md
delete mode 100644 docs/tech/installation/front-README.md
rename docs/tech/{installation.md => installation/overview.md} (57%)
diff --git a/.gitignore b/.gitignore
index 46dca8e..01693c4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,7 +3,12 @@ site/
docs/tech/architecture/definitions.md
docs/tech/architecture/CHANGELOG.md
docs/tech/api/openapi.yml
-files-from-repos/nginx-README.md
+
+files-from-repos/main-installation.md
+docs/tech/installation/TROUBLESHOOTING.md
+docs/tech/installation/USERS.md
+docs/tech/installation/https/base-setup.md
+docs/tech/installation/https/owncert.md
# python
.python-version
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 0cf9b7f..2dd6f00 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -17,19 +17,12 @@ setup:
stage: setup
before_script:
- apt-get update
- - apt-get install -y zip
script:
- ./utilities.sh # Running the script to setup directories and copy files
- - mkdir -p files-from-repos
- - rm -f files-from-repos/deployment-files.zip
- - pushd frontend/docker/
- - zip -r ../../files-from-repos/deployment-files.zip nginx-deployment/ -x nginx-deployment/compose-from-monorepo.yml
- - popd
artifacts:
paths:
- docs/tech
- files-from-repos
- - files-from-repos/deployment-files.zip
commit_zip:
stage: commit
@@ -38,7 +31,7 @@ commit_zip:
script:
- git config --global user.email "ci@gitlab.com"
- git config --global user.name "CI Bot"
- - git add files-from-repos/deployment-files.zip
+ - git add files-from-repos/intro-definition.zip
- git add files-from-repos/showcase-definition.zip
- git commit -m "Add authomatically deployment-files.zip"
- git push https://oauth2:${GITLAB_TOKEN}@gitlab.fi.muni.cz/inject/inject-docs.git HEAD:main -o ci.skip
diff --git a/.gitmodules b/.gitmodules
index 9e3a432..18d8062 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -12,3 +12,6 @@
[submodule "introductory-definition"]
path = introductory-definition
url = ../definitions/introductory-definition
+[submodule "docker-deployment"]
+ path = docker-deployment
+ url = ../docker-deployment
diff --git a/docker-deployment b/docker-deployment
new file mode 160000
index 0000000..7f2bd54
--- /dev/null
+++ b/docker-deployment
@@ -0,0 +1 @@
+Subproject commit 7f2bd5491fb02f9a040989db40b4adb63190a656
diff --git a/docs/index.md b/docs/index.md
index 32ec7bb..f47afe5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,7 +20,7 @@ Welcome! Whether you're responsible for technical deployment or facilitating tab
<div class="main-gridc" markdown>
<div class="navigation-main" markdown>
- [Installation](tech/installation.md){ .md-button }
+ [Installation](tech/installation/overview.md){ .md-button }
</div>
<div class="navigation-main" markdown>
[Exercise Preparation](INJECT_process/intro/overview.md){ .md-button }
@@ -54,7 +54,7 @@ Welcome! Whether you're responsible for technical deployment or facilitating tab
<br>
- **[Installation Guide ↲](tech/installation.md)**:
+ **[Installation Guide ↲](tech/installation/overview.md)**:
Step-by-step instructions for deploying IXP using Docker Compose and Nginx.
**[Architecture Overview](tech/architecture/overview.md)**:
diff --git a/docs/tech/installation/INSTALLATION.md b/docs/tech/installation/INSTALLATION.md
new file mode 100644
index 0000000..3f7f213
--- /dev/null
+++ b/docs/tech/installation/INSTALLATION.md
@@ -0,0 +1,23 @@
+# Installation (Docker)
+
+Start with choosing Docker Compose preset ([https](./https/base-setup.md) or [https-owncert](./https/owncert.md))
+these can be downloaded from [here](https://gitlab.fi.muni.cz/inject/docker-deployment/-/packages).
+After chosing one and downloading it continue with downloading backend and frontend source code to the Compose preset folders.
+
+Source code for frontend and backend can be downloaded in these following URLs
+- [Frontend](https://gitlab.fi.muni.cz/inject/frontend/-/releases)
+- [Backend](https://gitlab.fi.muni.cz/inject/backend/-/releases)
+
+
+## Compatibility
+
+To ensure that the downloaded versions of frontend and backend work correctly,
+check that they have the same version in the name on their respective `Releases` pages.
+E.g. `v2.0.0` of the frontend is fully compatible with `v2.0.0` of the backend.
+
+1. Unzip the individual archives.
+1. Rename the unzipped directories to `frontend` and `backend` respectively.
+1. Ensure that `.env` file in the root directory is set up correctly.
+ For any uncertainties please refer to the [tech overview](./overview.md) page or to pages of given presets
+ ([https](./https/base-setup.md) or [https-owncert](./https/owncert.md)).
+1. Run `docker compose up`, if any errors occur please refer to the troubleshooting guides.
diff --git a/docs/tech/installation/back-README.md b/docs/tech/installation/back-README.md
deleted file mode 100644
index faa0238..0000000
--- a/docs/tech/installation/back-README.md
+++ /dev/null
@@ -1,54 +0,0 @@
-### Local variables
-
-- `INJECT_DEBUG`: _boolean, default=false_ - Run the backend in debug mode. **Do not set in production.**
-- `INJECT_HOST_ADDRESSES`: _string, default=localhost_ - A comma-separated list of allowed hosts.
-- `INJECT_CORS_ALLOWED_ORIGINS`: _string, default=http://localhost_ - A comma-separated list of origins (domains) that are authorized to make cross-site HTTP requests.
-- `INJECT_NOAUTH`: _boolean, default=false_ - If set, authorization is turned off.
-- `INJECT_EMAIL_HOST`: _string, default=""_ - SMTP server address.
-- `INJECT_EMAIL_PORT`: _int, default=25_ - Port to use for the SMTP server defined in INJECT_EMAIL_HOST.
-- `INJECT_EMAIL_HOST_USER`: _string, default=""_ - Username to use for authentication to the SMTP server defined in _INJECT_EMAIL_HOST_.
-- `INJECT_EMAIL_HOST_PASSWORD`: _string, default=""_ - Password to use for the SMTP server defined in _INJECT_EMAIL_HOST_. This setting is used in conjunction with _INJECT_EMAIL_HOST_USER_ when authenticating to the SMTP server.
-- `INJECT_EMAIL_SENDER_ADDRESS`: _string, default=""_ - The sender address for automatic emails.
-- `INJECT_LOGS`: _string, default=backend-logs.log_ - Path to a file where to save logs.
-- `INJECT_DOMAIN`: _string, default=""_ - Domain where yours instance of the INJECT is available.
-
-
-
-### Running the Application with Docker:
-There is a `Dockerfile` present in this repository, which can be used to build an image of the current version of the backend.
-Image can be built with this command:
-```bash
-docker build -t backend .
-```
-Once the image is created, you can start the container with this command:
-```bash
-docker run --name backend -p8000:8000 -d backend gunicorn
-```
-You can access the backend the way described in the same way as when running locally.
-
-Image allows running of unit tests as well, this can be done via:
-```bash
-docker run --rm backend test
-```
-
-
-## Deployment
-The backend is made to be deployed using [gunicorn](https://gunicorn.org/) with [uvicorn](https://www.uvicorn.org/) workers.
-Specific versions of these servers are included in the poetry environment.
-To start the server, run this one-line command:
-```
-poetry python -m gunicorn ttxbackend.asgi:application -k uvicorn.workers.UvicornWorker
-```
-
-This will start a gunicorn server using uvicorn workers. `uvicorn` is required because `gunicorn`
-does not support websockets, which are necessary for GraphQL subscriptions.
-
-Currently, it is not recommended to use **more than 1 worker**.
-
-An additional environment variable `HOST_ADDRESSES` must be set with a comma-separated list of
-allowed host addresses.
-
-In Docker this can be done followingly:
-```bash
-docker run --name backend -e HOST_ADDRESSES="172.26.0.1,192.168.0.1" -p8000:8000 -d backend gunicorn
-```
\ No newline at end of file
diff --git a/docs/tech/installation/front-README.md b/docs/tech/installation/front-README.md
deleted file mode 100644
index 7975394..0000000
--- a/docs/tech/installation/front-README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-### Docker deployment
-
-The repository has a prepared Dockerfile so you can build the image:
-
-```
-docker build . -t inject-fe
-```
-
-Run the following command to deploy the docker container:
-
-```
-docker run -p 80:80 inject-fe
-```
-
-During runtime of the container it's required to bind the container to a given `backend` instance:
-
-```
-docker run -p 80:80 -e VITE_HTTP_HOST=secure-be.inject.muni.cz -e VITE_HTTP_WS=wss://secure-be.inject.muni.cz/ttxbackend/v1/graphql inject-fe
-```
-
-Please keep in mind that changing environment variables requires restarting the container if done during runtime.
\ No newline at end of file
diff --git a/docs/tech/installation.md b/docs/tech/installation/overview.md
similarity index 57%
rename from docs/tech/installation.md
rename to docs/tech/installation/overview.md
index a7b5599..0fe3ddb 100644
--- a/docs/tech/installation.md
+++ b/docs/tech/installation/overview.md
@@ -5,7 +5,7 @@ This separation allows for modular development, easier maintenance, and scalabil
Below, we'll walk you through the unified process of installation for frontend as well as for backend.
For a deeper understanding of the overall architecture of the IXP,
-you can refer to the [architecture overview](architecture/overview.md) in the documentation.
+you can refer to the [architecture overview](../architecture/overview.md) in the documentation.
## Prerequisites
@@ -28,20 +28,12 @@ These requirements ensure that the backend server can handle data processing eff
Make sure to install Docker and Docker Compose before proceeding with the installation.
-Download zipped installation files from [Gitlab](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/files-from-repos/deployment-files.zip?ref_type=heads&inline=false).
-
-These files include all necessary configuration files, scripts, and the `.env` file needed for deployment.
-Be sure that your server can access `https://gitlab.fi.muni.cz:5050` to pull Docker images.
-
{%
- include-markdown "../../files-from-repos/nginx-README.md"
- start="---
-tags: used_in_docs
----"
+ include-markdown "../../../files-from-repos/main-installation.md"
%}
## Conclusion
-By following the installation guide, you'll be able to successfully set up and run the IXP. After completing the installation, you may download this [showcase definition](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/files-from-repos/showcase-definition.zip?ref_type=heads&inline=false) and try to upload it to test the platform's functionality.
+By following the installation guide, you'll be able to successfully set up and run the IXP. After completing the installation, you may download this [Intro Definition](https://gitlab.fi.muni.cz/inject/inject-docs/-/raw/main/files-from-repos/intro-definition.zip?ref_type=heads&inline=false) and try to upload it to test the platform's functionality.
-If you encounter any bugs, please refer to the [Known Issues and Fixes](../known-issues.md) page for troubleshooting steps and solutions. If you require further assistance, don't hesitate to report them to us. The [Report issue](../report-issue.md) page includes instructions on how to report bugs.
\ No newline at end of file
+If you encounter any bugs, please refer to the [Known Issues and Fixes](../../known-issues.md) page for troubleshooting steps and solutions. If you require further assistance, don't hesitate to report them to us. The [Report issue](../../report-issue.md) page includes instructions on how to report bugs.
\ No newline at end of file
diff --git a/docs/tech/tech_overview.md b/docs/tech/tech_overview.md
index 7beacf5..1af62b7 100644
--- a/docs/tech/tech_overview.md
+++ b/docs/tech/tech_overview.md
@@ -7,7 +7,7 @@ Each part of this section is designed to help developers, system administrators,
### 1. Installation Guide
-- [Installation Guide](installation.md):
+- [Installation Guide](installation/overview.md):
This guide provides detailed, step-by-step instructions for deploying the IXP using Docker Compose and Nginx.
It covers prerequisites, environment variables configuration, HTTPS deployment, creating a superuser, and troubleshooting tips.
@@ -40,5 +40,5 @@ Each part of this section is designed to help developers, system administrators,
## Getting Started
-To begin your journey with the IXP, we recommend starting with the [Installation Guide](installation.md).
+To begin your journey with the IXP, we recommend starting with the [Installation Guide](installation/overview.md).
This guide will help you set up the platform using Docker Compose and Nginx, ensuring that all components are correctly configured and running smoothly.
diff --git a/mkdocs.yml b/mkdocs.yml
index 8c98a15..56d433a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,7 +13,14 @@ nav:
- Home: index.md
- Technical documentation:
- Overview: tech/tech_overview.md
- - Installation: tech/installation.md
+ - Installation:
+ - Overview: tech/installation/overview.md
+ - Installation: tech/installation/INSTALLATION.md
+ - HTTPS presets:
+ - Basic setup: tech/installation/https/base-setup.md
+ - Setup with your own certificate: tech/installation/https/owncert.md
+ - Troubleshooting: tech/installation/TROUBLESHOOTING.md
+ - Adding users: tech/installation/USERS.md
- System architecture:
- Overview: tech/architecture/overview.md
- Definition documentation:
@@ -71,3 +78,4 @@ plugins:
- redirects:
redirect_maps:
'report-bugs.md': 'report-issue.md'
+ 'tech/installation.md': tech/installation/overview.md
diff --git a/utilities.sh b/utilities.sh
index 98ddd02..967956d 100755
--- a/utilities.sh
+++ b/utilities.sh
@@ -9,6 +9,8 @@ git submodule status
# Create necessary directories
mkdir -p docs/tech
+mkdir -p docs/tech/installation
+mkdir -p docs/tech/installation/https
mkdir -p files-from-repos
# Copy files to the respective directories
@@ -16,5 +18,12 @@ cp ./backend/definitions/README.md ./docs/tech/architecture/definitions/README.m
cp ./backend/definitions/CHANGELOG.md ./docs/tech/architecture/definitions/CHANGELOG.md
cp ./backend/openapi.yml ./docs/tech/api/openapi.yml
cp ./frontend/docker/nginx-deployment/README.md ./files-from-repos/nginx-README.md
+
+cp ./docker-deployment/README.md ./files-from-repos/main-installation.md
+cp ./docker-deployment/TROUBLESHOOTING.md ./docs/tech/installation/TROUBLESHOOTING.md
+cp ./docker-deployment/USERS.md ./docs/tech/installation/USERS.md
+cp ./docker-deployment/https-owncert/README.md ./docs/tech/installation/https/owncert.md
+cp ./docker-deployment/https/README.md ./docs/tech/installation/https/base-setup.md
+
cp ./showcase-definition/assets/definition.zip ./files-from-repos/showcase-definition.zip
cp ./introductory-definition/assets/definition.zip ./files-from-repos/intro-definition.zip
--
GitLab