= Quarkus.io Search
A Quarkus-powered application that allows full-text search in websites of the Quarkus organization such as https://quarkus.io.
[[architecture]] == Architecture
The application is deployed on an OpenShift cluster, next to an OpenSearch instance.
It fetches the sources from quarkus.io and localized variants (pt.quarkus.io, ...) to index them, and exposes the search feature through a REST API.
The webpage at https://quarkus.io/guides calls that API to perform search.
// Source if you need to make changes: // https://miro.com/app/board/uXjVNtX8LlY=/?share_link_id=204315078797
image::architecture.png[Architecture diagram]
[[development]] == Development
[[development-sample]] === Using the built-in quarkus.io sample
By default, this will use a <<testing,small sample of quarkus.io included in this repository>>, which has the advantage of being faster to index on startup, but is incomplete.
To launch the application in dev mode:
quarkus dev
Then head over to http://0.0.0.0:9000/q/swagger-ui/ to try the service.
[[development-full]] === Using the actual quarkus.io data
To use the actual quarkus.io data without downloading it on each startup,
you should clone the https://github.com/quarkusio/quarkusio.github.io[quarkus.io repository]
manually and add a .env
file to your working directory:
_DEV_QUARKUSIO_GIT_URI=file:/home/myself/path/to/quarkusio.github.io _DEV_QUARKUSIO_LOCALIZED_JA_GIT_URI=file:/home/myself/path/to/ja.quarkus.io _DEV_QUARKUSIO_LOCALIZED_ES_GIT_URI=file:/home/myself/path/to/es.quarkus.io _DEV_QUARKUSIO_LOCALIZED_PT_GIT_URI=file:/home/myself/path/to/pt.quarkus.io _DEV_QUARKUSIO_LOCALIZED_CN_GIT_URI=file:/home/myself/path/to/cn.quarkus.io
Then the application will use data from that clone when indexing on startup.
If you also intend to run quarkus.io locally, and want links of search hits to redirect to your local instance of quarkus.io, you should also add this property:
_DEV_INDEXING_REPORTING_TYPE=github-issue
[[testing]] == Testing
Testing (and, by default <<development,dev mode>>) will use a small sample of quarkus.io included in this repository
at src/test/resources/quarkusio-sample.zip
(alongside with the localized site samples such as quarkusio-sample-cn.zip
,
quarkusio-sample-es.zip
, quarkusio-sample-ja.zip
, quarkusio-sample-pt.zip
).
This sample must itself be a git repository, so generating it can get technical.
Fortunately, there is a tool included in this project to generate the sample. To update the sample:
GuidesRef
.QuarkusIOSample.main()
using your IDE,If you set up your .env
file as descripted in <>,
you don't need to pass any argument.
+
Otherwise, pass as the path to your clone of quarkus.io,
followed by pairs of language code and path to corresponding localized site,
e.g.path/to/quarkus.io ja path/to/ja.quarkus.io es path/to/es.quarkus.io [...]
.
Add pairs for all cn
, es
, ja
, pt
language codes to update all samples at the same time.
[[production]] == Production
=== OpenShift configuration
The production environment uses OpenShift. You can generate the OpenShift configuration by running this:
quarkus build -DskipTests
The generated file will be in target/kubernetes/openshift.yml
.
=== Running it with podman
If you want to start a (production) container locally with podman, you can build one with the following command:
quarkus build -DskipTests -Dquarkus.container-image.build=true
Then start it this way:
podman pod create -p 8080:8080 -p 9000:9000 -p 9200:9200 --name search.quarkus.io
podman container run -d --name search-backend-0 --pod search.quarkus.io --cpus=2 --memory=2g -e "node.name=search-backend-0" -e "discovery.seed_hosts=localhost" -e "cluster.initial_cluster_manager_nodes=search-backend-0,search-backend-1,search-backend-2" -e "OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g" -e "DISABLE_SECURITY_PLUGIN=true" -e "cluster.routing.allocation.disk.threshold_enabled=false" opensearch-custom:latest podman container run -d --name search-backend-1 --pod search.quarkus.io --cpus=2 --memory=2g -e "node.name=search-backend-1" -e "discovery.seed_hosts=localhost" -e "cluster.initial_cluster_manager_nodes=search-backend-0,search-backend-1,search-backend-2" -e "OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g" -e "DISABLE_SECURITY_PLUGIN=true" -e "cluster.routing.allocation.disk.threshold_enabled=false" opensearch-custom:latest podman container run -d --name search-backend-2 --pod search.quarkus.io --cpus=2 --memory=2g -e "node.name=search-backend-2" -e "discovery.seed_hosts=localhost" -e "cluster.initial_cluster_manager_nodes=search-backend-0,search-backend-1,search-backend-2" -e "OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g" -e "DISABLE_SECURITY_PLUGIN=true" -e "cluster.routing.allocation.disk.threshold_enabled=false" opensearch-custom:latest
podman container run -it --rm --name search.quarkus.io --pod search.quarkus.io search-quarkus-io:999-SNAPSHOT
[[deployment]] == Deployment
=== Current process
Maintainers can review the application and update configuration/secrets on the OpenShift console.
There are two namespaces containing two separate deployments at the moment:
production
branch):main
branch):Deployment will happen automatically when pushing to the relevant branch.
Be careful about which configuration you change in the UI, as deployment may overwrite part of the topology.
=== Setting it up
Most of the process is automated, but if you need to deploy to a new cluster, you will need to set up a few things manually:
.github/workflows/deploy.yml
..github/workflows/deploy.yml
.search-quarkus-io-config
::GITHUB_STATUS_ISSUE_ID
: The number of an issue on quarkusio/search.quarkus.ioindexing.reporting.github
configuration properties for more details.search-quarkus-io-secret
::GITHUB_OAUTH
: a GitHub token that allows commenting/reopening/closing a GitHub issueindexing.reporting.github
configuration properties for more details.search-backend-config
::search-backend-secret
::[[license]] == License
This project is licensed under the Apache License Version 2.0.
The web assets in src/main/resources/web
are licensed under the Creative Commons Attribution 3.0 International License.