はじめに
Quarkusで動かすアプリケーションを思い立ったとき、まず道具は何を準備すればいいのかな？と考えるでしょう。最低限JDKがあればOKなのですが、Quarkus CLIがあると何かと役に立ちます。
この記事では、Quarkus CLIの主要な機能を確認し、どのような利用シーンで関わってくるのかを簡単にご紹介します。
この記事では、CLIの特徴を掴むことにフォーカスします。Quarkus自体の機能については最低限の解説に留めます。また、CLIの個々の機能を深堀りしませんので、詳細機能はヘルプなどでご確認ください。
検証環境
| 項目 | 内容 |
|---|---|
| OS | Windows 11 |
| JDK | GraalVM 21 |
| Quarkus CLI | 3.33 |
| コンテナランタイム | Podman |
Quarkus CLIとは
Quarkus CLIは開発者向けのツールであり、Quarkusのランタイムではありません。CLIがなくても、アプリケーションの開発や実行はできます。
「Quarkusをインストールするよ」という表現をすると、従来のアプリケーションサーバーに慣れた方だと「Quarkusというアプリケーションサーバーをインストールする」イメージを持たれるかもしれません。
またSaaS製品に慣れた方だと、GUIで提供されるサービスをコマンドラインで代替する、というイメージかもしれません。
この記事でインストールする Quarkus CLI は、開発者が行う各種操作を統一的にコマンドラインで実行するためのラッパーです。プロジェクトの作成、エクステンションの管理、開発モードでの起動、ビルド、コンテナイメージの作成などに対応します。
これらの操作には別の実行方法もありますが、Quarkus CLIを使うと、MavenやGradleなどの違いを意識する場面を減らし、共通のコマンド体系で操作できることが利点です。
Quarkus CLIのインストール
Windows ではいくつかインストール手順が提供されていますが、 Scoop を使った手順が最もシンプルです。Scoop がまだインストールされていない場合は scoop.sh を参照してください。
scoop install quarkus-cli
インストール後、次のコマンドでバージョンが確認できます。ここで表示されるのはCLIのバージョン番号であり、アプリで利用するQuarkusのバージョンではない点に注意が必要です。
quarkus --version
macOS では brew install quarkusio/tap/quarkus（Homebrew）、その他の方法（JBang など）については 公式ドキュメント を参照してください。
Quarkus CLIの機能
Quarkus CLIは、次のような機能を提供します。開発者が必要とする一連の機能をCLIで統一感のあるコマンド体系で操作することができます。
| 機能 | 説明 |
|---|---|
| プロジェクト管理 | 新プロジェクトの作成やエクステンション管理 |
| 実行 | 開発モードおよび通常の起動 |
| ビルド | 実行モジュールの作成 |
| コンテナ運用 | コンテナイメージの作成やデプロイ |
Maven／Gradleとの関係
既存プロジェクトの起動やビルドでは、Quarkus CLIは Maven／Gradleのプラグインを呼び出すラッパーとして機能します。Mavenプロジェクトでは、次のように対応します。
quarkus dev # ./mvnw quarkus:dev に相当
quarkus build # ./mvnw install に相当
CLIの便利さは、起動やビルドだけでなく、次のような操作でも感じられます。
| 操作 | CLIを使うと便利な点 |
|---|---|
| プロジェクト作成 | 作成条件をコマンドとして共有し、自動化にも利用できる |
| エクステンション管理 | コマンドで検索・追加・削除でき、依存関係を手で編集する場面を減らせる |
| コンテナイメージ作成 |
quarkus image build でイメージ作成を指示できる |
| バージョン指定 | プロジェクト作成時に、使用するプラットフォームのリリースを指定できる |
以降では、これらの操作を実際のコマンドで確認します。
プロジェクトの作成と編集
quarkus create app と CodeQuarkus の違い
Quarkus プロジェクトを作成する方法は大きく2つあります。どちらも生成される結果は同じですが、CLIのほうが指示をコンパクトに共有でき、よりスピーディに開発を開始できるという利点があります。
| 方法 | 特徴 | 向いている場面 |
|---|---|---|
quarkus create app（CLI） |
ターミナルから直接生成。エクステンションをコマンドラインで指定 | ターミナルから離れずに作業したい、自動化したい |
| code.quarkus.io（CodeQuarkus） | ブラウザで エクステンション をチェックボックスで選びながら ZIP ダウンロード | 初回・エクステンション を検索しながら選びたい |
プロジェクト作成
作業フォルダで新しいプロジェクトを作成します。
quarkus create app com.example:hello-quarkus --extension="rest" --java=21 --stream=3.33
ここではパッケージ名とプロジェクト名（groupIdとartifactId）、その他パラメータを指定してプロジェクトを作成しています。
実行すると、作業フォルダ上にプロジェクトが直接生成されます。
主なオプションは次のとおりです。全てのオプションを参照するには quarkus create app --help で確認してください。
| オプション | 指定 |
|---|---|
| --extension | エクステンション、カンマ区切りで複数指定可能 |
| --java | アプリのターゲットになるJDKのバージョン |
| --stream | 使用するQuarkusのバージョン |
| --gradle | Gradleを使用する |
エクステンションの管理
「エクステンション」は Quarkus の機能拡張単位です。プロジェクト作成時に指定し忘れたエクステンションを後から追加したり、不要なエクステンションを削除したりできます。
エクステンションの一覧表示
# プロジェクトに現在インストール済みの Extension を表示
quarkus ext list
# インストール可能な Extension を一覧表示（多数表示される）
quarkus ext list --installable
# キーワードで絞り込む
quarkus ext list --installable --search hibernate
quarkus ext list --installable で表示される エクステンション は 数百件 あります。REST、セキュリティ、データベース、AI（LangChain4j、MCP Server）など幅広いカテゴリが揃っています。
エクステンションの追加、削除
プロジェクトに含まれるエクステンションを後から追加、削除できます。
# エクステンションの追加
quarkus ext add hibernate-orm-panache
# 複数のエクステンション追加
quarkus ext add hibernate-orm-panache jdbc-postgresql
# エクステンションの削除
quarkus ext rm hibernate-orm-panache
エクステンションの追加・削除は pom.xml の <dependencies> を書き換えるのと同等です。ただこちらのほうがより簡潔に指示することができます。
アプリケーションの起動
Quarkus CLI には、アプリを起動するコマンドが準備されています。
開発者は quarkus dev を使うことが多いでしょう。
# 開発モードでの実行
quarkus dev
# 通常の実行
quarkus build
quarkus run
開発モードでは、コードの動的コンパイルやDev UIの実行が可能になります。プロファイルはdevが選択されます。
より本番に近い形で実行するために quarkus run を使用できます。これはビルド済Jarファイルの起動と同等であるため、事前にビルドを行う必要があります。
正常に起動できていれば、ブラウザで http://localhost:8080/hello にアクセスすると Hello from Quarkus REST と表示されます。
ビルドとデプロイ
Quarkusでは、JVM上でアプリを動かす一般的なJavaアプリケーションとしての使い方の他、ネイティブアプリに変換してJVM無しで動かすパターンにも対応します。
これらは起動方法を意識してビルドする必要があります。
# JVMビルド
quarkus build
# ネイティブビルド（ローカルOS向け）
quarkus build --native
# ネイティブビルド（コンテナ向け）
quarkus build --native -D"quarkus.native.container-build=true" -DskipTests
Windowsでネイティブビルドを行う場合、ローカルにGraalVMとC/C++ビルド環境が必要になる点は注意が必要です。
またWindows向けに作成したネイティブ実行ファイルは、この記事で扱うLinuxコンテナでは実行できません。そのため、Windows環境でLinuxコンテナ向けのネイティブ実行ファイルを作成するには、コンパイル用コンテナ上でビルドを行うquarkus.native.container-buildの指定が適切です。
ビルドが完了すると、成果物はMavenの場合 target フォルダに生成されます。
ネイティブビルドは JVM ビルドより大幅に時間がかかります。
コンテナイメージの作成
次のコマンドで、アプリケーションのビルドとコンテナイメージの作成をまとめて実施します。
イメージ作成時には、次のDockerfileが使用されます。パラメータで別のDockerfileを指定することもできます。
| モード | デフォルトのDockerfile | パラメータ |
|---|---|---|
| JVM | src/main/docker/Dockerfile.jvm |
-D"quarkus.podman.dockerfile-jvm-path=src/..." |
| ネイティブ | src/main/docker/Dockerfile.native |
-D"quarkus.podman.dockerfile-native-path=src/..." |
# JVMビルド コンテナイメージ作成
quarkus image build --podman
# ネイティブビルド コンテナイメージ作成
quarkus image build podman --native -D"quarkus.native.container-build=true"
ここではコンテナランタイムにPodmanを使用しています。成果物はPodmanに直接格納されますので、次のコマンドで確認および実行ができます。
# イメージの確認
podman images
# コンテナのローカル実行
podman run -i --rm -p 8080:8080 <username>/hello-quarkus:1.0.0-SNAPSHOT
<username> はデフォルトで OS のユーザー名が使われます（podman images で確認できます）。application.properties に quarkus.container-image.group=mycompany を追加すると変更できます。
プラットフォームへのデプロイ
次のコマンドで、quarkus image build の処理に加え、指定のプラットフォームへの反映までをまとめて実施します。プラットフォームはk8sやOpenShiftなどが指定可能です。
quarkus deploy openshift -D"quarkus.openshift.deploy=true" -D"quarkus.openshift.route.expose=true"
application.propertiesの利用
ビルド系のコマンドはパラメータが多くなります。
これらのパラメータを application.properties に指定しておくことで、シンプルな指定にでき、チームでの共有も容易になります。
# コンテナイメージの設定
quarkus.native.container-build=true
# OpenShift デプロイ設定
quarkus.openshift.route.expose=true
おわりに
Quarkus CLIは、開発を行うにあたり必須なツールではありません。
劇的な工数削減に寄与するわけではありませんが、統一的なコマンド体系で必要な操作が実施でき開発体験は向上すると考えられます。
まずは quarkus create app でプロジェクトを作り、quarkus dev で開発を進めてみてください。エクステンションの追加やコンテナ化が必要になった際にも、CLIを活用してみてください 