WildFly Admin Containers

waco (WildFly admin containers) is a command line tool to build and run WildFly containers of different versions in different operation modes (domain and standalone). The container images are based on the official WildFly images but are intended more for the development and testing of WildFly and its management tools (CLI and console). The container names and published ports follow default values based on the WildFly version.

• Installation
• Versions
• Images
• Containers
• Commands
  • Build
  • Standalone
    • Start
    • Stop
  • Domain
    • Domain Controller
      • Start
      • Stop
    • Host Controller
      • Start
      • Stop
    • Topology
      • Start
      • Stop
  • Images
  • PS
  • Management Clients
    • Console
    • CLI

Installation

Precompiled binaries are available for macOS, Linux, and Windows.

Brew

brew tap hpehl/tap
brew install waco

Cargo

cargo install waco

Shell Completions

wget https://github.com/hpehl/waco/raw/main/completions/waco.bash -O /etc/bash_completion.d/waco
source /etc/bash_completion.d/waco

wget https://github.com/hpehl/waco/raw/main/completions/_waco -O /usr/local/share/zsh/site-functions/_waco
autoload -U compinit && compinit
autoload -U _waco

wget https://github.com/hpehl/waco/raw/main/completions/waco.fish -O ~/.config/fish/completions/waco.fish

wget https://github.com/hpehl/waco/raw/main/completions/waco.elv -O ~/.elvish/lib/waco.elv

Invoke-WebRequest -Uri https://github.com/hpehl/waco/raw/main/completions/_waco.ps1 -OutFile "$HOME\.config\powershell\_waco.ps1"
. "$HOME\.config\powershell\_waco.ps1"

Versions

Most commands require a WildFly version expression. Version expressions are either short versions, multipliers, ranges, enumerations, or a combination of them. They follow this BNF:

<expression> ::= <expression> "," <element> | <element>
<element> ::= <multiplier> "x" <range> | <multiplier> "x" <short_version> | <range> | <short_version>
<range> ::= <short_version> ".." <short_version> | ".." <short_version> | <short_version> ".." | ".."
<multiplier> ::= <nonzero_number> | <two_digit_number>
<short_version> ::= <major> | <major> "." <minor>
<major> ::= <two_digit_number> | <three_digit_number>
<minor> ::= <nonzero_number> | <two_digit_number>
<three_digit_number> ::= <nonzero_number> <number> <number>
<two_digit_number> ::= <nonzero_number> <number>
<number> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<nonzero_number> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Examples

• 10
• 26.1
• 3x35
• 23..33
• 25..
• ..26.1
• ..
• 5x33..35
• 20,25..29,2x31,3x32,4x33..35

All supported versions are listed here.

Images

The images are based on the official WildFly images, are hosted at https://quay.io/organization/waco, and come in three variants:

• Standalone: quay.io/waco/waco-sa
• Domain controller: quay.io/waco/waco-dc
• Host controller: quay.io/waco/waco-hc

Each image contains tags for all supported versions.

Image Modifications

The images are based on the default configuration (subsystems, profiles, server groups, socket bindings et al.) of the corresponding version. Unless specified otherwise, the images use these configuration files to start WildFly:

• Standalone: standalone.xml
• Domain controller: domain.xml and host-primary.xml
• Host controller: domain.xml and host-secondary.xml

All images add a management user admin:admin and allowed origins for

• http://localhost:1234 (used by console dev mode)
• http://localhost:8888 (used by console dev mode)
• http://localhost:9090 (used by HAL standalone)
• http://hal.github.io (latest online console)
• https://hal.github.io (latest online console)

Domain and host controller images are changed so that no servers are configured.

Containers

Naming

The default name for containers is waco-<type>-<version>[-index]

• Type: sa|dc|hc - standalone, domain or host controller
• Version: <major><minor>
• Index: If multiple containers of the same version and type are used, a zero-based index is added to the name.

Ports

If not specified otherwise, the standalone and domain controller containers publish their HTTP and management ports based on the WildFly version:

• 8080 → 8<major><minor>
• 9900 → 9<major><minor>

So for WildFly 34, the port mappings are 8340 and 9340, and for WildFly 26.1, the port mappings are 8261 and 9261. If multiple containers of the same version are used, the port is increased by one from the second container onwards.

waco start 26.1,28..30,2x32,3x35

Commands

[!IMPORTANT] Most commands require podman to be present with docker as a fallback. The console command opens the default web browser and the cli command requires a JVM.

Currently, the following commands are supported:

Command line tool to build and run WildFly containers in different versions and operation modes.

Usage: waco <COMMAND>

Commands:
  build     Build WildFly images
  start     Start a standalone server
  stop      Stop a standalone server
  dc        Start and stop a domain controller
  hc        Start and stop a host controller
  topology  Start and stop a topology defined as YAML
  ps        List running images
  console   Open the management console
  cli       Connect to the CLI
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Build

If not specified otherwise, the build command builds standalone, domain, and host controller images based on the official WildFly images. The images contain specific modifications and a management user with a predefined username and password.

Predefined images for all supported versions are available at https://quay.io/organization/waco. If you want to change the username and password, you can build your own local image.

Build WildFly images

Usage: waco build [OPTIONS] <wildfly-version>

Arguments:
  <wildfly-version>  A single WildFly version or version range

Options:
  -u, --username <username>  The username of the management user [default: admin]
  -p, --password <password>  The password of the management user [default: admin]
      --standalone           Build standalone images only
      --domain               Build domain controller and host controller images only
      --chunks <chunks>      Build the images in chunks of this size. If not specified, the images are built in one go.
  -h, --help                 Print help
  -V, --version              Print version

Examples

waco build 34
waco build 34 --username alice --password "Admin#70365"
waco build 10,23,34 --standalone
waco build 20..29 --domain
waco build 10,20..29,34
waco build .. --chuncks 5

Standalone

Start

Start a standalone server

Usage: waco start [OPTIONS] <wildfly-version> [-- [wildfly-parameters]...]

Arguments:
  <wildfly-version>        A single WildFly version or version range
  [wildfly-parameters]...  Parameters passed to the standalone server

Options:
  -n, --name <name>              The name of the standalone server [default: waco-sa-<major><minor>].
                                 Not allowed when multiple versions are specified.
  -p, --http <http>              The published HTTP port [default: 8<major><minor>].
                                 Not allowed when multiple versions are specified.
  -m, --management <management>  The published management port [default: 9<major><minor>].
                                 Not allowed when multiple versions are specified.
  -o, --offset <offset>          The offset added to the published HTTP and management ports.
                                 Not allowed when multiple versions are specified.
      --operations <operations>  A comma seperated list of operations to bootstrap the standalone server.
                                 Can be provided multiple times.
      --cli <cli>                A file with operations to bootstrap the standalone server
  -h, --help                     Print help
  -V, --version                  Print version

Examples

waco start 34
waco start 3x34
waco start 30..35
waco start 34 --name foo
waco start 34 --name bar --offset 100
waco start 34 --http 8080 --management 9990
waco start 34 --operations "/subsystem=logging/console-handler=CONSOLE:write-attribute(name=level,value=DEBUG)"
waco start 34 --offset 100 -- --server-config=standalone-microprofile.xml

Stop

Stop a standalone server

Usage: waco stop [OPTIONS] [wildfly-version]

Arguments:
  [wildfly-version]  A single WildFly version or version range

Options:
  -n, --name <name>  The name of the standalone server [default: waco-sa-<major><minor>]
  -a, --all          Stop all running standalone servers. If specified with a version,
                     stop all running standalone servers of that version.
  -h, --help         Print help
  -V, --version      Print version

Examples

waco stop 34
waco stop 30..35
waco stop 34 --name foo
waco stop 34 --all
waco stop --all

Domain

Domain Controller

Start

Start a domain controller

Usage: waco dc start [OPTIONS] <wildfly-version> [-- [wildfly-parameters]...]

Arguments:
  <wildfly-version>        A single WildFly version or version range
  [wildfly-parameters]...  Parameters passed to the domain controller

Options:
  -n, --name <name>              The name of the domain controller [default: waco-dc-<major><minor>].
                                 Not allowed when multiple versions are specified.
  -p, --http <http>              The published HTTP port [default: 8<major><minor>].
                                 Not allowed when multiple versions are specified.
  -m, --management <management>  The published management port [default: 9<major><minor>].
                                 Not allowed when multiple versions are specified.
  -o, --offset <offset>          The offset added to the published HTTP and management ports.
                                 Not allowed when multiple versions are specified.
  -s, --server <server>          Manage servers of the domain controller.
                                 Servers are specified as a comma seperated list of <name>[:<server-group>][:<offset>][:start].
                                 The option can be specified multiple times.
                                 <name>          The name of the server. This part is mandatory and must be first.
                                                 All other parts are optional.
                                 <server-group>  The name of the server group. Allowed values are 'main-server-group' or 'msg',
                                                 and 'other-server-group' or 'osg'. If not specified, 'main-server-group' is used.
                                 <offset>        The port offset. If not specified, 100 is used from the second server onwards.
                                 start           Whether to start the server.
      --operations <operations>  A comma seperated list of operations to bootstrap the domain controller.
                                 Can be provided multiple times.
      --cli <cli>                A file with operations to bootstrap the domain controller
  -h, --help                     Print help
  -V, --version                  Print version

Examples

waco dc start 34
waco dc start 3x34
waco dc start 30..35
waco dc start 34 --name foo
waco dc start 34 --name bar --offset 100
waco dc start 34 --http 8080 --management 9990
waco dc start 34 --server s1:start
waco dc start 35 --server s1,s2,s3,s4:osg,s5:osg
waco dc start 34 --server s1:start,s2,s3 --server s4:osg:start,s5:osg,s6:osg
waco dc start 34 --name dc \
  --server server-one:main-server-group:start \
  --server server-two:main-server-group:10 \
  --server server-three:other-server-group:20

Stop

Stop a domain controller

Usage: waco dc stop [OPTIONS] [wildfly-version]

Arguments:
  [wildfly-version]  A single WildFly version or version range

Options:
  -n, --name <name>  The name of the domain controller [default: waco-dc-<major><minor>]
  -a, --all          Stop all running domain controllers. If specified with a version,
                     stop all running domain controllers of that version.
  -h, --help         Print help
  -V, --version      Print version

Examples

waco dc stop 34
waco dc stop 30..35
waco dc stop 34 --name foo
waco dc stop 34 --all
waco dc stop --all

Host Controller

Start

Start a host controller

Usage: waco hc start [OPTIONS] <wildfly-version> [-- [wildfly-parameters]...]

Arguments:
  <wildfly-version>        A single WildFly version or version range
  [wildfly-parameters]...  Parameters passed to the domain controller

Options:
  -n, --name <name>
          The name of the host controller [default: waco-hc-<major><minor>].
          Not allowed when multiple versions are specified.
  -d, --domain-controller <domain-controller>
          The name of the domain controller [default: waco-dc-<major><minor>].
          Required if different versions are specified.
  -u, --username <username>
          The username to connect to the domain controller [default: admin]
  -p, --password <password>
          The password to connect to the domain controller [default: admin]
  -s, --server <server>
          Manage servers of the host controller.
          Servers are specified as a comma seperated list of <name>[:<server-group>][:<offset>][:start].
          The option can be specified multiple times.
          <name>          The name of the server. This part is mandatory and must be first.
                          All other parts are optional.
          <server-group>  The name of the server group. Allowed values are 'main-server-group' or 'msg',
                          and 'other-server-group' or 'osg'. If not specified, 'main-server-group' is used.
          <offset>        The port offset. If not specified, 100 is used from the second server onwards.
          start           Whether to start the server.
      --operations <operations>
          A comma seperated list of operations to bootstrap the host controller.
          Can be provided multiple times.
      --cli <cli>
          A file with operations to bootstrap the host controller
  -h, --help
          Print help
  -V, --version
          Print version

Examples

waco hc start 34
waco hc start 3x34
waco hc start 30..35 --domain-controller dc
waco hc start 34 -n foo -d dc -u alice -p "Admin#70365"
waco hc start 34 --server s1
waco hc start 3x34 --server s1,s2,s3:osg
waco hc start 35 --name hc \
  --server server-one:main-server-group:start \
  --server server-two:main-server-group:10 \
  --server server-three:other-server-group:20

Stop

Stop a host controller

Usage: waco hc stop [OPTIONS] [wildfly-version]

Arguments:
  [wildfly-version]  A single WildFly version or version range

Options:
  -n, --name <name>  The name of the host controller [default: waco-hc-<major><minor>]
  -a, --all          Stop all running host controllers. If specified with a version,
                     stop all running host controllers of that version.
  -h, --help         Print help
  -V, --version      Print version

Examples

waco hc stop 34
waco hc stop 30..35
waco hc stop 34 --name foo
waco hc stop 34 --all
waco hc stop --all

Topology

[!WARNING] The topology commands are not yet implemented. You can work around with the dc and hc commands though:

waco dc start 35 -n dc -s s1,s2,s3,s4:osg,s5:osg
waco hc start 32,33,2x35 -d dc -s s1,s2,s3:osg
waco console 35

Open http://localhost:9350/console/index.html#runtime;path=domain-browse-by~topology

Start

Start a topology

Usage: waco topology start <setup>

Arguments:
  <setup>  The topology setup

Options:
  -h, --help     Print help
  -V, --version  Print version

Stop

Stop a topology

Usage: waco topology stop <setup>

Arguments:
  <setup>  The topology setup

Options:
  -h, --help     Print help
  -V, --version  Print version

The topology setup is a YAML file like this:

version: 34
hosts:
  - name: dc
    domain-controller: true
  - name: host1
    servers:
      - name: server-one
        group: main-server-group
        auto-start: true
      - name: server-two
        group: main-server-group
        offset: 100
      - name: server-three
        group: other-server-group
        offset: 200
      - name: server-four
        group: other-server-group
        offset: 300
  - name: host2
    version: 33
    servers:
      - name: server-one
        group: main-server-group
      - name: server-two
        group: main-server-group
        offset: 100
      - name: server-three
        group: other-server-group
        offset: 200
  - name: host3
    servers:
      - name: server-one
        group: main-server-group
      - name: server-two
        group: other-server-group
        offset: 100
      - name: server-three
        group: other-server-group
        offset: 200

Images

List all available standalone, domain and host controller images

Usage: waco images

Options:
  -h, --help     Print help
  -V, --version  Print version

PS

List running standalone, domain and host controller containers

Usage: waco ps [OPTIONS]

Options:
      --standalone  List standalone containers only
      --domain      List domain controller and host controller containers only
  -h, --help        Print help
  -V, --version     Print version

Management Clients

Console

Open the management console

Usage: waco console [OPTIONS] [wildfly-version]

Arguments:
  [wildfly-version]  A single WildFly version or version range.
                     If omitted the console is opened for all running standalone and domain controller containers.

Options:
  -n, --name <name>              The name of the standalone server or domain controller [default: waco-sa|dc-<major><minor>].
                                 Not allowed when multiple versions are specified.
  -m, --management <management>  The published management port. Not allowed when multiple versions are specified.
  -h, --help                     Print help
  -V, --version                  Print version

Examples

waco console
waco console 34
waco console 30..35
waco console 34 --management 9990

CLI

If not already present, this command downloads the wildfly-cli-client.jar and jboss-cli.xml of the specified version to the $TMPDIR.

Connect to the CLI

Usage: waco cli [OPTIONS] [wildfly-version] [-- [cli-parameters]...]

Arguments:
  [wildfly-version]    A single WildFly version.
                       Can be omitted if only one standalone or domain controller is running.
  [cli-parameters]...  Parameters passed to the CLI

Options:
  -n, --name <name>              The name of the standalone server or domain controller [default: waco-sa|dc-<major><minor>].
                                 Not allowed when multiple versions are specified.
  -m, --management <management>  The published management port
  -u, --username <username>      The username to connect to the CLI [default: admin]
  -p, --password <password>      The password to connect to the CLI [default: admin]
  -h, --help                     Print help
  -V, --version                  Print version

Examples

waco cli
waco cli 34
waco cli 34 -- --command "/subsystem=logging/console-handler=CONSOLE:write-attribute(name=level,value=DEBUG)"