diff --git a/.github/workflows/userdocumentation.yml b/.github/workflows/userdocumentation.yml new file mode 100644 index 0000000..1786bb5 --- /dev/null +++ b/.github/workflows/userdocumentation.yml @@ -0,0 +1,17 @@ +name: Update user documentation +on: + push: + branches: [ main ] + paths: + - 'userdocs/**' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Trigger website update + uses: peter-evans/repository-dispatch@v1 + with: + token: ${{ secrets.CI_PAT }} + repository: onecx/userdocs + event-type: dispatch-build-website diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..e623b5a --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,3 @@ +name: onecx-theme +title: Theme Management +version: latest diff --git a/docs/modules/onecx-theme-ui/nav.adoc b/docs/modules/onecx-theme-ui/nav.adoc new file mode 100644 index 0000000..4d552a9 --- /dev/null +++ b/docs/modules/onecx-theme-ui/nav.adoc @@ -0,0 +1 @@ +* xref:index.adoc[User Interface] diff --git a/docs/modules/onecx-theme-ui/pages/index.adoc b/docs/modules/onecx-theme-ui/pages/index.adoc new file mode 100644 index 0000000..52feda3 --- /dev/null +++ b/docs/modules/onecx-theme-ui/pages/index.adoc @@ -0,0 +1,4 @@ + +== onecx-theme-ui + +include::onecx-theme-ui-docs.adoc[opts=optional] diff --git a/docs/modules/onecx-theme-ui/pages/onecx-theme-ui-docs.adoc b/docs/modules/onecx-theme-ui/pages/onecx-theme-ui-docs.adoc new file mode 100644 index 0000000..81c38d1 --- /dev/null +++ b/docs/modules/onecx-theme-ui/pages/onecx-theme-ui-docs.adoc @@ -0,0 +1,112 @@ +== OneCX Theme UI + + +=== What is Theme Management? +OneCX Theme Management refers to the systematic process of capturing, +organizing, storing, and retrieving Theme items. + + +=== Overview +OneCX Theme is a comprehensive solution for managing +Theme items for OneCX products in a user-friendly and efficient manner. +In this document we are only referring to the OneCX Theme User Interface (UI) of +OneCX Theme Management. + +The UI for this Theme management component is designed +to provide an intuitive and user-friendly experience for managing +Theme items in the cloud-native environment built with Quarkus. + + +=== Getting Started +To start developing the OneCX Theme UI, you need to +set up your local development environment. It’s recommended that you use +WSL as the runtime for your application, as shown in the figure below. +If you are using a different runtime, please check that you meet the +requirements below. + +==== Prerequisites + +Before you begin, ensure you have the following installed: + +* Java Development Kit (JDK) version 17 +* Maven build tool +* Git +* Docker + Docker Compose +* Windows Subsystem for Linux (WSL) - recommended +* NodeJS + +==== Clone the Repository + +Start by cloning the required repositories to your local machine using +the following command: + +[source,bash] +---- +git clone https://github.com/onecx/onecx-Theme-ui.git +git clone https://github.com/onecx/Theme-dev.git +---- + +The repository `onecx-Theme` contains the source code of +the OneCX Theme product. +The repository `onecx-Theme-ui` contains the source code of +the OneCX Theme UI as part of the product. + +==== Update local DNS resolution +Assuming you are using WSL, updating the local host file for local +development allows you to map domain names to specific IP addresses, +making it easier to test and debug applications using custom domain names +instead of IP addresses. To enable multiple services on the same port, +we use traefik as a reverse proxy. A running traefik container is +therefore essential for your local setup to route your traffic to the +appropriate Docker containers based on hostnames. + +*It is recommended that the WSL host file and the Windows host file are aligned. +Unless you have disabled this behaviour, the WSL host file will be automatically +generated from the Windows host file when WSL is restarted.* + +===== Update Windows host file +Open the file `C:\Windows\System32\drivers\etc\hosts` in your favorite +editor and add the following entries: + +[source,bash] +---- +127.0.0.1 postgresdb +127.0.0.1 keycloak-app +127.0.0.1 traefik +127.0.0.1 onecx-Theme-ui +127.0.0.1 onecx-Theme-bff +127.0.0.1 onecx-Theme-svc +---- + +===== Update WSL host file +If needed, update the file `\etc\hosts` in `your` favorite linux editor and add the +same entries like above. + +==== Starting OneCX dependencies +In a local development environment, Docker Compose is used to define and +manage multiple containers as a single application stack. It enables +developers to easily start, stop, and configure all the necessary +services and dependencies required by OneCX Theme Management using a +simple configuration file. + +[source,bash] +---- +mkdir onecx-Theme +cd onecx-Theme +docker compose up -d traefik postgresdb pgadmin keycloak-app +---- + +* `traefik`: Traefik is an ingress controller for Kubernetes deployments +that enables dynamic traffic routing and load balancing based on defined +rules and configurations. +* `postgresdb`: PostgreSQL is an open-source relational database +management system. It is used as persistence layer for storing and +managing data of OneCX products, providing reliability and +scalability. +* `pgadmin`: pgAdmin is an open-source administration and development +platform that offers a user-friendly graphical interface for managing +and interacting with the local PostgreSQL database. +This is optional. +* `keycloak`: Keycloak is an open-source identity and access management +system that simplifies authentication, authorization, and single sign-on +for web and mobile applications.