WildFly deployment utlity
wildfly-deploy
is a small PowerShell utility that offers an automation framework to quickly and easily setup a web-server on a local machine.
Table of contents
Usage
- Check the
default.ini
configuration file located under theconf
folder; - If needed, add custom configuration to the
custom.ini
configuration file in the same configuration folder; - Run the
Deploy-WildFly.ps1
script located with the appropriate parameter for the action to execute:- configure
- install
- show
- uninstall
- Check the logs.
Pre-requisites
Permissions
This script requires administrator rights to be run.
PowerShell version
This script requires PowerShell version 5.0 or later to be run.
PowerShell Tool Kit
This script makes use of functions from the PowerShell Tool Kit (PSTK) module. It must be installed on the local machine or copied in a lib
folder at the root of the directory.
.wildfly-deploy
+---conf
+---lib
| \---PSTK
+---powershell
\---res
WildFly PowerShell Module
This script requires the WildFly PowerShell Module (PSWF) module. It must be installed on the local machine or copied in a lib
folder at the root of the directory.
.wildfly-deploy
+---conf
+---lib
| +---PSTK
| \---PSWF
+---powershell
\---res
Java
WildFly requires Java Platform, Standard Edition (Java SE). For version requirement, please refer to the corresponding WildFly documentation.
Configuration
Script configuration
The default configuration of the utility is stored into default.ini
. This file should not be amended. All custom configuration must be made in the custom.ini
file. Any customisation done in that file will override the default values.
Below is an example of configuration file:
[Paths]
# Configuration directory
ConfDirectory = \conf
# Directory containing the libraries
LibDirectory = \lib
[Filenames]
# Server properties
ServerProperties = server.ini
# Custom configuration
CustomProperties = custom.ini
Remark: Sections (and comments) are ignored in these configuration files. You can make use of them for improved readability.
Service configuration
To configure the Windows service for WildFly, please edit the configuration file service.properties
located in the conf
directory.
Java Virtual Machine configuration
To configure the Java Virtual Machine (JVM), please edit the configuration file jvm.properties
located in the conf
directory.
Security
When running in unattended mode, the script will use the administrator credentials provided in the configuration file. The password provided must be stored as a plain-text representation of a secure string encrypted using the encryption key provided in the directory res\security
.
In order to generate the required value, please use the command below with the corresponding password:
ConvertFrom-SecureString -SecureString (ConvertTo-SecureString -String "<password>" -AsPlainText -Force) -Key (Get-Content -Path ".\res\security\encryption.key")
Parameters
Action
The action parameter takes four possible values:
- Configure
- Install
- Show
- Uninstall
Configure
The configure option will configure an existing instance of WildFly.
Install
The install option will install a new instance of WildFly on the local machine.
Reload
The reload option will reload the application server.
Restart
The restart option will restart the WildFly service.
Show
The show option will display the configuration of the script.
Start
The start option will start the WildFly service.
Stop
The stop option will stop the WildFly service.
Uninstall
The uninstall option will remove an existing instance of WildFly from the local machine.
Version
The optional version parameter allows you to specify the version of WildFly to deploy dynamically without having to edit the configuration file. It takes precedence over the values defined in custom.ini
and default.ini
.
Unattended
The unattended switch allows you to run the script in silent mode without any interaction. This relies on all configuration properties having been properly defined, especially the admin user credentials.
Logs
Transcript log files are generated in the log
directory of the script.
- The naming convention is as follows:
<Action>-WildFly_<Timestamp>.log
. - The format of the log is:
<Timestamp> <Message type> <Message>
Below is an example of a successful installation log:
2020-02-10 14:19:07 INFO Installation of WildFly 11.0.0.Final
2020-02-10 14:19:07 INFO Checking distribution source files
2020-02-10 14:19:08 CHECK Distribution file integrity check successful
2020-02-10 14:19:08 INFO Extracting WildFly to "C:\WKFS\WildFly"
2020-02-10 14:19:47 INFO Configuring "" environment variable
2020-02-10 14:19:47 INFO Configuring Java options
2020-02-10 14:19:47 CHECK Java options configured successfully
2020-02-10 14:19:47 INFO Configuring interfaces
2020-02-10 14:19:47 INFO Configuring addresses for management interface
2020-02-10 14:19:47 INFO Configuring addresses for public interface
2020-02-10 14:19:47 CHECK Interfaces configured successfully
2020-02-10 14:19:47 INFO Configuring ports
2020-02-10 14:19:47 INFO Configuring standard socket port offset
2020-02-10 14:19:47 INFO Configuring ajp socket
2020-02-10 14:19:47 INFO Configuring http socket
2020-02-10 14:19:47 INFO Configuring https socket
2020-02-10 14:19:47 INFO Configuring management-http socket
2020-02-10 14:19:47 INFO Configuring management-https socket
2020-02-10 14:19:47 INFO Configuring txn-recovery-environment socket
2020-02-10 14:19:47 INFO Configuring txn-status-manager socket
2020-02-10 14:19:47 CHECK Port numbers configured successfully
2020-02-10 14:19:47 INFO Configuring WildFly service
2020-02-10 14:19:48 INFO Installing WildFly service
2020-02-10 14:19:48 INFO Starting WildFly service (WildFly11)
2020-02-10 14:19:58 INFO Creating Administrator role
2020-02-10 14:20:02 CHECK Administrator security role has been successfully created
2020-02-10 14:20:02 INFO Add user admin to management realm
2020-02-10 14:20:03 CHECK User admin successfully added
2020-02-10 14:20:03 INFO Grant role Administrator to user group Administrators
2020-02-10 14:20:06 CHECK Administrator security role has been successfully granted
2020-02-10 14:20:06 INFO Enabling role-based access control security model
2020-02-10 14:20:09 CHECK RBAC security model has been successfully enabled
2020-02-10 14:20:09 INFO Reloading WildFly
2020-02-10 14:20:12 CHECK WildFly 11.0.0.Final installation complete
Known issues
Failure to remove files
When uninstalling the application, it may happen that an access denied error is thrown when trying to remove the files.
This can be due to multiple causes:
- A ghost Java process still running that applies a lock on the files. Manually terminating the Java process resolves the issue and the uninstallation can be re-run successfully.
- A file opened in an application such as a text editor can apply a lock on the specific file. Closing all relevant applications removes the lock and the uninstallation can be re-run successfully.
Roadmap
- Enable HTTPS configuration
- Enable LDAP configuration