Setting up a Skyve instance
The following page describes the steps required to set up an on-premise Skyve server instance. This is a high-level overview and assumes a basic understanding of the technologies involved. For more detailed information, refer to the documentation for the specific technologies.
Recommended requirements
The minimum server requirements are:
- 4GB RAM for Linux and 8GB RAM for Windows
- Java JDK 17 (this is the JDK for Java 17)
- Wildfly 30+
- Disk space requirements vary based on the application, especially if the database and content repository share the same drive. However, most applications should run smoothly with at least 50GB of drive space.
Installation steps
Windows
- Download and install Java 17 or 21 (requires UAC)
- This can be downloaded from https://adoptium.net/temurin/releases/?os=windows&arch=x64&package=jdk
- Change the defaults to also install the
JAVA_HOME
environment variable - Complete the wizard and close after the installation has completed
- Configure Environment Variables (requires UAC)
- Search for
environment
in the Start menu and open Edit the system environment variables - Click the Environment Variables button
- If
JAVA_HOME
is not present- Click New… in the System variables section
- Enter
JAVA_HOME
for the variable name - Click Browse Directory… and browse to where the JDK was just installed, should be similar to
C:\Program Files\Eclipse Adoptium\jdk-17xxx
- Click OK
- If the system has 8GB memory or more, click New… in the System variables section
- Enter “JAVA_OPTS” for the variable name
- Enter variable value
-Xms4G -Xmx4G -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=2G
- Click OK 3 times and then close the System window
- Search for
- Download and install Wildfly
- This can be downloaded from https://www.wildfly.org/downloads/
- Unzip the downloaded
wildfly-x.x.x.Final.zip
- Move to the root of a drive, e.g.
C:\
- Install any database specific drivers into Wildfly, e.g. for Microsoft SQL Server:
- Download the SQL Server JDBC Driver
- Extract the JDBC driver
- Navigate to
C:\wildfly-26.1.2.Final\modules\system\layers\base\com\microsoft\
- Create a new folder
sqlserver
- Open
sqlserver
and create a new foldermain
- Copy the downloaded
mssql-jdbc-12.6.1.jre11.jar
into main - Create a new file
module.xml
and paste the contents
<?xml version="1.0" encoding="utf-8"?>
<module xmlns="urn:jboss:module:1.3" name="com.microsoft.sqlserver">
<resources>
<resource-root path="mssql-jdbc-12.6.1.jre11.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>
- Edit
wildfly/standalone/configuration.xml
- Add the SQL server driver configuration to the
drivers
section of the xml
- Add the SQL server driver configuration to the
<driver name="sqlserver" module="com.microsoft.sqlserver">
<xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
</driver>
- Depending on your port-forwarding configuration, you may need to change the HTTPS listen port from
8443
to443
<socket-binding name="https" port="${jboss.https.port:443}"/>
- Find <interface name=”public”> and change to the following
<interface name="public">
<inet-address value="${jboss.bind.address:0.0.0.0}"/>
</interface>
- Configure Wildfly as a Windows service (requires UAC)
- go to the directory
C:\wildfly\docs\contrib\scripts
- copy the folder
service
- go to the directory
C:\wildfly\bin
- paste the service folder there
- Hold down shift and right click on the
C:\wildfly\bin\service
folder - Select Open Powershell Window Here
- Type
.\service.bat install
and press Enter - Click Yes to the User Account Control prompt
- The last line of text should say “Service Wildfly installed”
- Close the Powershell window
- Click the Windows key and type services, and open the Services control panel
- Find the Wildfly service and double click
- Change Startup Type to Automatic (Delayed Start)
- Click Start then OK
- Check the service starts and does not stop straight away
- go to the directory
- Create a new folder called
content
inC:\
- Create a new folder called
addins
inC:\content\
- Update your application
appName.json
and specify thecontent
path,addins
path and environmentidentifier
- Deploy the application
- Copy
skyve-content-x.x.x.zip
toC:\content\addins
- Copy
appName.war.zip
,appName.json
andappName-ds.xml
toC:\wildfly-x.x.x.Final\standalone\deployments
, replacing any existing files - Unzip
appName.war.zip
- Right click -> New Text File
- Rename the text file to
appName.war.dodeploy
(make sure no.txt
on the end)
- Copy
-
Once authenticated, remove the
identifier
andbootstrap
from the json file and redeploy the application - If required, create an inbound firewall rule for TCP port 443
- Click start and type firewall and select “Windows Defender Firewall”
- Click “Advanced settings”
- Click “Inbound Rules” on the select, then “New Rule…” on the right
- Select Port and click Next
- Leave TCP selected and type
443
into “Specific local ports” and click Next - Leave “Allow the connection” selected and click Next
- Uncheck Private and Public networks and click Next
- Enter Wildfly as the name, and “Network port for Wildfly application server for Skyve application.” as the Description
- Click Finish
Linux (Ubuntu)
Assume you are working from a sudoer
- Install OpenJDK >= 17
sudo apt update
sudo apt install default-jdk
- Test java is installed
which java
java -version
- Create the wildfly user
sudo groupadd -r wildfly
sudo useradd -r -g wildfly -d /opt/wildfly -s /sbin/nologin wildfly
- Install wildfly >= 27
wget https://github.com/wildfly/wildfly/releases/download/31.0.1.Final/wildfly-31.0.1.Final.tar.gz -P /tmp
- Untar to /opt
sudo tar xf /tmp/wildfly-31.0.1.Final.tar.gz -C /opt/
- Create a symbollic link
sudo ln -s /opt/wildfly-31.0.1.Final /opt/wildfly
- Change wildfly install owner
sudo chown -RH wildfly: /opt/wildfly
- Run as a service
sudo mkdir -p /etc/wildfly
sudo cp /opt/wildfly/docs/contrib/scripts/systemd/wildfly.conf /etc/wildfly/
sudo cp /opt/wildfly/docs/contrib/scripts/systemd/launch.sh /opt/wildfly/bin/
- Make wildfly/bin content executable
sudo sh -c 'chmod +x /opt/wildfly/bin/*.sh'
sudo cp /opt/wildfly/docs/contrib/scripts/systemd/wildfly.service /etc/systemd/system/
- Reload service definitions
sudo systemctl daemon-reload
- Start the wildfly service
sudo systemctl start wildfly
- Check it
sudo systemctl status wildfly
- Start the service automatically at boot time
sudo systemctl enable wildfly
- Optionally open port 8080
sudo ufw allow 8080/tcp
- Optionally change Wildfly JVM memory settings
- Edit
/opt/wildfly/bin/standalone.conf
and locate
- Edit
#
# Specify options to pass to the Java VM.
#
if [ "x$JBOSS_JAVA_SIZING" = "x" ]; then
JBOSS_JAVA_SIZING="-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m"
fi
and replacing with (for example)
if [ "x$JBOSS_JAVA_SIZING" = "x" ]; then
JBOSS_JAVA_SIZING="-Xms4g -Xmx4g -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=512m"
fi
- To start, stop, restart the wildfly service:
sudo service wildfly restart
- availabile options are
start
/status
/stop
/restart
Other datasource options
There are a number of optional settings for the application data source file myApplication-ds.xml
. The file provided from the Skyve project creator is usually satisfactory, however the following describes other options which you may need to consider.
Option | Values | Description |
---|---|---|
jta | true/false | this should be false for Skyve applications unless you are using ccm (see below) - refer to http://www.mastertheboss.com/jboss-server/jboss-datasource/demystifying-datasource-jta-and-xa-settings-on-jboss-wildfly |
use-ccm | true/false | Essentially this will log leaked connections - “The Cached Connection Manager is used for debugging data source connections and supporting lazy enlistment of a data source connection in a transaction, tracking whether they are used and released properly by the application. At the cost of some overhead, it can provide tracing of the usage, and make sure that connections from a data source are not leaked by your application. Although that seems like an advantage, in some instances it’s considered an anti-pattern and so to be avoided.” (from JBoss AS 5 Administration Guide). |
Additional information is available from a number of sources, for example for example.
Additional configuration
The validation stanza provides Wildfly with the required configuration to create new connections as needed.
From this page “If the validation query executes successfully, the pool will return that connection. If the query does not execute successfully, the pool will create a new connection”. A typical validation stanza is as follows:
<validation>
<check-valid-connection-sql>select 1</check-valid-connection-sql>
<validate-on-match>true</validate-on-match>
<background-validation>false</background-validation>
<background-validation-millis>0</background-validation-millis>
</validation>
<statement>
<prepared-statement-cache-size>0</prepared-statement-cache-size>
<share-prepared-statements>false</share-prepared-statements>
</statement>
Note that the sql statement for <check-valid-connection-sql>
is dialect specific - so consider your specific configuration carefully.
From the documentation:
<prepared-statement-cache-size>
- the number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a LRU cache. The default is 0 (zero), meaning no cache.<share-prepared-statements>
- with prepared statement cache enabled whether two requests in the same transaction should return the same statement
Configuring ports
To configure which ports will be used for accessing the application, modify the
<socket-binding name="http" port="${jboss.http.port:8080}"/>
<socket-binding name="https" port="${jboss.https.port:8443}"/>
For example, for external access, typically you would assign as follows:
<socket-binding name="http" port="${jboss.http.port:80}"/>
<socket-binding name="https" port="${jboss.https.port:443}"/>
Create a folder for content
Skyve includes content management - for file uploads and images - the repository requires a dedicated folder to persist files. The user credential running wildfly (for example) will need read-write permissions to this folder.
Create a folder for addins
Typically, it’s easiest to add one add-ins subfolder for all your projects, and refer to it directly in all project JSON settings files (note the trailing slash):
// Add-ins settings
"addins": {
// Where to look for add-ins - defaults to <content.directory>/addins/
"directory": "C:/_/content/addins/"
},
Load the skyve-content-<version>.zip
(this manages content locally) into the addins by:
- right-click your project and Run As -> Maven install
- the
skyve-content-<version>.zip
will be downloaded to your target folder - the results of the maven install will include this location, usually<project>\target\
[INFO] --- maven-dependency-plugin:2.8:copy (copy-content-addin-dependency) @ myproject ---
[INFO] Configured Artifact: org.skyve:skyve-content:8.0.0:zip
[INFO] Copying skyve-content-8.0.0.zip to C:\_\j11\myproject\target\skyve-content-8.0.0.zip
- copy the
skyve-content-<version>.zip
to the directory specified in the JSON settings file above.
Install Wildfly as a Service
So that the Skyve application will be always available, install the wildfly service, ensuring that the service will have read/write access to the content folder.
The following link may be useful for linux installations.
For Windows:
- Configure Wildfly as a Windows service (requires UAC)
- go to the directory
C:\wildfly\docs\contrib\scripts
- copy the folder “service”
- go to the directory
C:\wildfly\bin
- paste the service folder there
- Hold down shift and right click on the
C:\wildfly\bin\service
folder - Select Open Powershell Window Here
- Type
.\service.bat install
and press Enter - Click Yes to the User Account Control prompt
- The last line of text should say “Service Wildfly installed”
- Close the Powershell window
- Click the Windows key and type services and click the Services control panel
- Find the Wildfly service and double click
- Change Startup Type to Automatic (Delayed Start)
- Click Apply
- Click Start then OK
- Check the service starts and does not stop straight away
- Open your browser and go to http://localhost:8080 and check the Wildfly splash screen shows
- go to the directory
Next Common Wildfly configuration settings
Previous Installing and configuring a Skyve development environment