Skyve application configuration
To deploy a Skyve application, there are typically three artefacts:
- the application
.war
folder - the datasource
ds.xml
file - the properties
.json
file
For example, if your Skyve application is called ‘myApplication’, these will be:
myApplication.war
myApplication-ds.xml
myApplication.json
The ds.xml
and .json
remain on the server you are deploying to, and are customised for that specific instance, so that when you are deploying a new version of your Skyve application, the instance settings do not need to be adjusted.
When deploying the Skyve application web archive ‘war’, ensure that matching configuration settings are updated in the associated ds.xml
and .json
configuration files.
Ensure the ds.xml
file uses a connection string and credentials corresponding to the setting for the database driver above
Ensure the .json
properties file has been updated for the specific instance including:
- content directory
- context url
- database dialect
- smtp settings
- maps and other api keys
- environment identifier
Finally, ensure that the user credential that will run the wildfly service has read/write permissions to the wildfly folder and the content folder created above.
Configuring Captcha for the sign in page
Skyve has two Captcha options that you can use, Google Recaptcha
and Cloudflare Turnstile
. To enable one of the two options, follow the steps below:
Google Recaptcha
First, sign up for a Google Recaptcha key as follows:
- Visit Google Recaptcha console and sign in
- Click Admin console in the top right corner
- Click the + button in the toolbar to create a new site
- Enter a label to identify what this key will be for (the name of your Application)
- Select reCAPTCHA v2 and select the type of challenge (the default is fine)
- Enter the URL of your Skyve application
- Read and accept the terms of use
- Click Submit
Once you have received your site and secret key, copy your key into the Startup Configuration section of the Admin menu of your Skyve application:
- From the Admin menu, open Configuration
- Change tabs to the Startup Configuration tab
- Scroll down to the Security Settings section
- Select ‘Google Recaptcha’ as the CAPTCHA Type
- Enter the Site and secret keys and then press Save at the top of the form.
Alternatively, you can place the API key in the project JSON file under api
-> googleRecaptchaSiteKey:
and googleRecaptchaSecretKey:
.
// API Settings
api: {
googleRecaptchaSiteKey: "xxxxxxxxxxx",
googleRecaptchaSecretKey: "xxxxxxxxxxx",
}
Cloudflare Turnstile (requires skyve > 9.1.0)
First, sign up for a Cloudflare Turnstile key as follows:
- Visit Cloudflare and sign up
- Click Turnstile in the sidebar menu on the left
- Click the ‘Add site’ button to add a new site
- Enter a site name to identify what this key will be for (the name of your Application)
- Enter the domain name of your Skyve application e.g ‘app.website.com’ or ‘website.com’
- Select the widget mode you wish to use.
- Click ‘Create’
Once you have received your site key and secret key, copy your key into the Startup Configuration section of the Admin menu of your Skyve application:
- From the Admin menu, open Configuration
- Change tabs to the Startup Configuration tab
- Scroll down to the Security Settings section
- Select ‘Cloudflare Turnstile’ as the CAPTCHA Type
- Enter the Site Key and Secret Key and then press Save at the top of the form.
Alternatively, you can place the API keys in the project JSON file under api
// API Settings
api: {
cloudflareTurnstileSiteKey: "xxxxxxxxxxx",
cloudflareTurnstileSecretKey: "xxxxxxxxxxx",
}
Changing the project URL
Normally, the project name will be the name of the .war
- which will be the context on the URL for example https://skyve.org/myApplication
where myApplication
is also the name of the project.
If you only need to change the base URL (for example, from https://skyve.org/
to https://myDomain.com/
), you can do this by specifiying the URL in the myApplication.json
settings file. Similarly, if your application will operate from the base URL then make the change to the URL in the myApplication.json
file and set the context setting to /
for example:
// URL settings - various SKYVE URL/URI fragments - useful for linking and mailing
"url": {
// server URL
"server": "https://myDomain.com",
// web context path
"context": "/",
// home path
"home": "/"
},
Note that URLs without a specified port will require you to change the Wildlfy port settings suitably, for example:
<socket-binding name="http" port="${jboss.http.port:80}"/>
<socket-binding name="https" port="${jboss.https.port:443}"/>
However if you need to change the project for a different URL context, like https://skyve.org/tax_management
, then there’s a few simple steps you need to take to make that work.
- Remove the project from your wildfly server (and ensure the
myApplication.war
is removed from the deployments area). - Edit the project
pom.xml
file to change the name of the.war
to be built:
change
<groupId>myApplication</groupId>
<artifactId>myApplication</artifactId>
<version>1.0</version>
<packaging>war</packaging>
<name>myApplication</name>
to
<groupId>myApplication</groupId>
<artifactId>tax_management</artifactId>
<version>1.0</version>
<packaging>war</packaging>
<name>tax_management</name>
- Rename the
.json
settings file frommyApplication.json
totax_management.json
- Update the project
.json
file for the new context from
// URL settings - various SKYVE URL/URI fragments - useful for linking and mailing
"url": {
// server URL
"server": "https://skyve.org",
// web context path
"context": "/myApplication",
// home path
"home": "/"
},
to
// URL settings - various SKYVE URL/URI fragments - useful for linking and mailing
"url": {
// server URL
"server": "https://skyve.org",
// web context path
"context": "/tax_management",
// home path
"home": "/"
},
- Rename the
myApplication-ds.xml
totax_management-ds.xml
- Maven update the project (for example, in eclipse, right-click the project, choose Maven and update Project)
- Add the project to your wildfly server
Note that
- when deploying, you may need to manually create the
tax_management-ds.xml.dodeploy
andtax_management.war.dodeploy
signal files. - You need to manually remove the previous
myApplication.war
if you didn’t in the preparation stage. - If you didn’t rename the previous
myApplication.json
andmyApplication-ds.xml
, you should these files to avoid confusion (for example if the datasource name is the same for both the oldmyApplication-ds.xml
andtax_management-ds.xml
).
Protecting the ds.xml credentials
The ds.xml password is clear text. While it is possible to use an encrypted password for the datasource connection, this is of limited use.
Instructions are available if this is required, for example Encrypt password for Wildfly.
This approach has limited use as it is really just a level of indirection. The credentials need to be decrypted and so a key needs to be stored. This means the file containing the key then needs to be protected on the file system - and if this is possible, it would seem reasonable to simply apply that level of protection to the ds.xml file (and other config) directly.
Example deployment instructions for Single Sign-on
The following steps are to install an instance of XXX onto a vanilla Windows 10.
–JAVA
Install Java JDK
Set JAVA\_HOME
to location of the Java root directory - e.g.
C:\Java\jdk11...
Set PATH
to include Java\bin
- e.g. C:\Java\jdk11...\bin
copy sqljdbc4.jar
and sqljdbc\_auth.dll
to java\jdk\jre\lib\ext
–JBOSS
Install Wildfly (unzip and copy to c:\
)
check/update wildfly\bin\run.conf
settings for memory -
JAVA\_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=512m
(1 occurence)
check/update wildfly\bin\service.bat
settings for calls to run.bat
to
include the options -c default -b 0.0.0.0
(2 occurrences)
e.g. call run.bat -c default -b 0.0.0.0 < .r.lock >> run.log
2>&1
as administrator, install service (from command prompt, in wildfly\bin\
issue service install
set service to run as XXX\svc.wildfly user
(from service msc, change user
and startup type - don’t check name as it will try to resolve as
svc.wildfly@NET.XXX)
–KERBEROS
copy krb5.conf to wildfly\bin
copy spnego-r7.jar to wildfly\server\default\lib\
add clauses from web.xml\_amendment.txt
(wildfly\..deploy\jbossweb.sar\web.xml
or
wildfly\..\deploy\jbossweb-tomcat55.sar\conf\web.xml
)
add clauses from login-config.xml\_amendment.txt
(wildfly\..\default\conf\login-config.xml
)
copy hello\_spnego.jsp wildfly\..\root.war
check HTTP SPNs added to both svc.wildfly user and machine
–DEPLOYMENT
Stop Wildfly service
Copy \\dev\C\$\\_\Example
to C:\\_\Example
check C:\\_\Example\javaee\arc\_ds.xml
connection string
check C:\\_\Example\content\repository.xml
connection strings (x2)
check C:\\_\Example\content\workspaces\arc\workspace.xml
connection string
check C:\\_\Example\content\workspaces\default\workspace.xml
connection string
check C:\\_\Example\apps\repository\customers\arc\arc.xml
icon
Copy C:\\_\Example\javaee\arc.ear & arc\_ds.xml
to
C:\wildfly\server\default\deploy\
Start JBoss service
–CHECKS
check http://<server>.net.arc:8080/hello\_spnego.jsp
if “Failure unspecified at GSS-API level (Mechanism level: Checksum failed)- check SPNs
check http://<server>.net.arc:8080/arc/init.biz
if error - check that you have an account in XXX, check
C:\wildfly\standalone\log\server.log
to see your user
principal is being recognised