Quarkus Roq Generator
It provides a command to run any Quarkus web application and extract it in a directory as purely static files (html and assets).
Roq Generator is already included as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq , Follow Standalone installation section to use it standalone.
|
Generating your static site
You can generate your static site using:
QUARKUS_ROQ_GENERATOR_BATCH=true mvn package quarkus:run -DskipTests
By default, it will generate the static site in the target/roq
directory.
When used within the Roq Static Site Generator extension, it is already pre-configured to generate the whole site (which can be disabled with site.generator=false ). In standalone mode, by default, only the / (index.html) and static/** will be generated. Follow the next section to configure the selection.
|
You can now try or deploy your static website with any static file server. We provide a small tool to try it:
$ jbang app install --verbose --fresh --force roq@quarkiverse/quarkus-roq
$ roq decks->!+(ia3andy/decks)
Serving: target/roq/
Server started on port http://localhost:8181
at any time you can open the dev-ui to see the Roq Generator selection. |
Github Pages configuration
You can configure Roq to deploy Github Pages, Netlify, or any static website server.
Check how the Roq blog is deployed on GitHub pages here.
Advanced Usage
Configure the static selection
You can configure application paths which should be generated as static files from the Quarkus configuration:
quarkus.roq.generator.paths=/,/static/**,/bar/
By convention paths ending with / such as /bar/ are considered as html pages and with generate html pages such as /bar/index.html .
|
The glob syntax is only working with fixed paths. Paths which uses query params or path params should be either manually entered or provided at runtime from the Java code. |
You can also manually specify the generated output path:
quarkus.roq.generator.custom-paths."/api/foo"=/foo.json
Configure the dynamic selection
You need to produce a RoqSelection
singleton from your application:
@Produces
@Singleton
RoqSelection produce() {
return new RoqSelection(List.of(
SelectedPath.builder().html("/roq?name=foo").build(), (1)
SelectedPath.builder().html("/blog/hello-roq").build(), (2)
SelectedPath.builder().path("/api/hello?name=foo").outputPath("/hello-foo.json").build())); (3)
}
1 | Using .html() means we want to generate an html page from roq?name=foo content, when unspecified we generate the output path automatically, in that case it would be /roq-name-foo/index.html . |
2 | in that case it will generate /blog/hello-roq/index.html . |
3 | It is also possible to manually specify the output path. In that case it will generate /hello-foo.json from /api/hello?name=foo content. |
Use @Transactional if you need to iterate through database entities to prepare your selection. For example if the blog post ids are stored in a database.
|
Deploy to GitHub Pages
To create your GitHub Page with Roq:
-
Open your GitHub repository page
-
Go to Settings→Page
-
Pick:
Source: GitHub Actions
-
Click on Static Html "Configure" button
-
Paste this content (to adapt with Gradle):
## Deploy to GH-Pages for your Quarkus Roq blog.
name: Quarkus Roq Deploy CI
on:
push:
branches: [ main ]
workflow_dispatch:
env:
QUARKUS_ROQ_GENERATOR_BATCH: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK 21
uses: actions/setup-java@v4
with:
java-version: 21
distribution: 'temurin'
cache: 'maven'
- name: Get GitHub Pages URL
id: get_url
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url');echo "ghp-url=$url";
path=$(echo "$url" | sed -E 's|https?://[^/]+(/.*)?|\1|')
url=$(echo "$url" | sed -E 's|(https?://[^/]+).*|\1|')
if [ -z "$path" ]; then
path="/"
fi
echo "SITE_URL=$url"; echo "SITE_URL=$url" >> $GITHUB_ENV;
echo "SITE_PATH=$path"; echo "SITE_PATH=$path" >> $GITHUB_ENV;
- name: Build & Generate Blog
run: mvn -B package quarkus:run -DskipTests -Dquarkus.http.root-path=$SITE_PATH -Dsite.url=$SITE_URL
- name: Upload site as artifact
uses: actions/upload-artifact@v4
with:
name: site
path: target/roq
retention-days: 1
deploy:
runs-on: ubuntu-latest
needs: build
permissions:
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Download Built site
uses: actions/download-artifact@v4
with:
name: site
path: _site
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
This is process will be improved in the near future (follow progress). |
Standalone installation
It is included and pre-configured as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq .
|
You can also use it standalone on any Quarkus application. If you want to use this extension standalone, you need to add the io.quarkiverse.roq:quarkus-roq-generator
extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
<dependency>
<groupId>io.quarkiverse.roq</groupId>
<artifactId>quarkus-roq-generator</artifactId>
<version>1.0.5</version>
</dependency>
Extension Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
---|---|---|
The selected paths to include in the static website Glob syntax is authorized for non-dynamic resources (without query or path params) For dynamic paths selection, produce a
Environment variable: |
list of string |
|
You can configure the path to get content from and the output path that will be generated. Environment variable: |
Map<String,String> |
|
Output directory for the static website relative to the target directory Environment variable: |
string |
|
Build as a CLI to export the static website Environment variable: |
boolean |
|
Timeout for generation in seconds Environment variable: |
long |
|