Setup4j: Difference between revisions

Latest revision as of 21:13, 22 September 2026

Setup4j is step 4 of the Install Guide. It tells Commander4j where your database is, tests the connection, and creates the tables. It is also the tool you run after every upgrade (see Upgrading). Its window title is Host Administration.

Everything Setup4j saves goes into one file, xml/hosts/hosts.xml in the Commander4j folder. If you later set up the scanner web application on Apache Tomcat, you copy that file to the server (see Installation).

Before you start

You need a database ready and these details from Install Database: server name, instance name or port, database name, and either a username and password or the decision to use Windows login.

Open Setup4j

On Windows, open the Start menu, find the Commander4j folder and click Setup4j. On a Mac it is in the Commander4j folder inside Applications. On Linux run Setup4j from the install folder.

The window has three parts:

Connections on the left: the list of databases Commander4j knows about. A fresh install shows three examples, one for each database type. None of them can connect to anything; they are there to show what a filled-in connection looks like. Users see this list when they log in, so delete the examples once your own connection works.
The form in the middle: the details of the connection selected on the left.
Buttons on the right: the actions described below.

Add your connection

The easiest way is to edit the example that matches your database type.

Click the example in the Connections list, for instance SQL Server Example Only.
Change Description to something users will recognise, such as Production or Test.
Check Database Type is right (mySQL, SQL Server or Oracle). The Driver and JDBC URL fields fill themselves in from the other fields; you never type into them.
Fill in the connection fields for your database:

Field	SQL Server Express	MySQL / MariaDB	Oracle
Server	`localhost`, or the server's name or IP address from another PC	`localhost` or the server name	server name
Database	`Commander4j`	`Commander4j`	leave blank
Port	`1433`	`3306`	`1521`
SID	`SQLEXPRESS` (the instance name; blank for a default instance)	leave blank	the service name or SID
Username / Password	the SQL login, or blank with Integrated Security ticked	`commander4j` and its password	the schema user and password
Integrated Security	tick to log in as the Windows user (Option A in Install Database)	leave unticked	leave unticked
Trust Server Cert	tick	leave unticked	leave unticked
Collation / CharSet	leave as set	`utf8mb4_0900_ai_ci` / `utf8mb4` (MariaDB: `utf8mb4_general_ci` / `utf8mb4`)	leave as set

The other fields (timeouts, timezone, DB Date Time, DB Select Limit, DB Schema, Unique ID) already hold the right values for the database type. Leave them alone.

To start from a blank connection instead, click Add DB Connection. Delete DB Connection removes the selected one.

Test the connection

Click Connect / Check DB. One of three things happens:

Connected, and the Version Information panel shows Actual Schema Version as -1. Correct for a brand-new empty database: it means Setup4j reached the database and found no Commander4j tables yet. Go to the next section.
Connected, and the actual and required versions match, with green ticks. The database is already set up for this version of Commander4j. Click Save Configuration and you are done.
An error message. The status bar at the bottom explains what went wrong. Common causes: TCP/IP not enabled in SQL Server, wrong server or instance name, wrong password, or SQL Server still in Windows-only authentication mode. See Install Database and Install Guide#If something goes wrong.

Create or upgrade the tables

When the actual version is lower than the required version, the AUTO Update DB button becomes available. Click it. Setup4j creates or upgrades every table, view and function, then loads the standard data (menus, permissions, language text, example records).

On an empty database this takes several minutes, and the progress bar at the bottom moves slowly at first. Let it finish. When it does, both versions match and show green ticks.

If the update stops with an error, it is almost always a permissions problem: the database user is not allowed to create tables or views. Fix the permissions as described in Install Database, drop any tables that were created, and run AUTO Update DB again.

Save

Click Save Configuration. Setup4j writes hosts.xml and you can close it.

Tidy-up, once your own connection works: select each example connection and either untick Enabled (it stays in the file but users no longer see it) or click Delete DB Connection.

Next step: First Login.

Other things Setup4j can do

Enable Splash Screen and Single Instance control how the application starts. Single Instance stops a user opening Commander4j twice on the same PC.
Protect Configuration with Password stops users opening Setup4j and changing connections.
Assign to Service links a connection to the Windows interface service on a Full install. See Install Interface Services.
DB Schema Report lists the tables and columns in the connected database.
Update Mode, URL App Update and URL Hosts Update configure automatic update checks. They are optional and can be left alone.
Open Hosts File switches to a different hosts.xml, for example when maintaining connections for a Tomcat server.

@@ Line 1: / Line 1: @@
+'''Setup4j''' is step 4 of the [[Install Guide]]. It tells Commander4j where your database is, tests the connection, and creates the tables. It is also the tool you run after every upgrade (see [[Upgrading]]). Its window title is ''Host Administration''.
-[[file:Setup4j-1.png|600px]]
+Everything Setup4j saves goes into one file, <code>xml/hosts/hosts.xml</code> in the Commander4j folder. If you later set up the scanner web application on Apache Tomcat, you copy that file to the server (see [[Installation]]).
+== Before you start ==
-When you first install C4J and run the Setup4j program you will see some examples of database connections (sometimes referred to has hosts).
+You need a database ready and these details from [[Install Database]]: server name, instance name or port, database name, and either a username and password or the decision to use Windows login.
-Note that none of the examples will be able to connect to a database - they are there purely as examples of what kind of information you may want to populate for each type of database.
+== Open Setup4j ==
-Before using the Setup4j program you need to have installed a database and you will need to have created a database user account for the application to connect with.
+On Windows, open the Start menu, find the ''Commander4j'' folder and click '''Setup4j'''. On a Mac it is in the Commander4j folder inside Applications. On Linux run <code>Setup4j</code> from the install folder.
-The settings are stored in a file called [[hosts.xml]] and you will need to copy this file once it's been configured into your Apache Tomcat webapps application folder if you are planning to setup the web interface for mobile devices.
+[[file:Setup4j-1.png|800px]]
-Versions 10.34 and newer now support Windows integrated authentication for SQL Server.
+The window has three parts:
+* '''Connections''' on the left: the list of databases Commander4j knows about. A fresh install shows three examples, one for each database type. None of them can connect to anything; they are there to show what a filled-in connection looks like. Users see this list when they log in, so delete the examples once your own connection works.
+* '''The form''' in the middle: the details of the connection selected on the left.
+* '''Buttons''' on the right: the actions described below.
+== Add your connection ==
+The easiest way is to edit the example that matches your database type.
+# Click the example in the Connections list, for instance ''SQL Server Example Only''.
+# Change '''Description''' to something users will recognise, such as ''Production'' or ''Test''.
+# Check '''Database Type''' is right (mySQL, SQL Server or Oracle). The ''Driver'' and ''JDBC URL'' fields fill themselves in from the other fields; you never type into them.
+# Fill in the connection fields for your database:
+{| class="wikitable"
+! Field !! SQL Server Express !! MySQL / MariaDB !! Oracle
+|-
+| '''Server''' || <code>localhost</code>, or the server's name or IP address from another PC || <code>localhost</code> or the server name || server name
+|-
+| '''Database''' || <code>Commander4j</code> || <code>Commander4j</code> || leave blank
+|-
+| '''Port''' || <code>1433</code> || <code>3306</code> || <code>1521</code>
+|-
+| '''SID''' || <code>SQLEXPRESS</code> (the instance name; blank for a default instance) || leave blank || the service name or SID
+|-
+| '''Username''' / '''Password''' || the SQL login, or blank with ''Integrated Security'' ticked || <code>commander4j</code> and its password || the schema user and password
+|-
+| '''Integrated Security''' || tick to log in as the Windows user (Option A in [[Install Database]]) || leave unticked || leave unticked
+|-
+| '''Trust Server Cert''' || tick || leave unticked || leave unticked
+|-
+| '''Collation''' / '''CharSet''' || leave as set || <code>utf8mb4_0900_ai_ci</code> / <code>utf8mb4</code> (MariaDB: <code>utf8mb4_general_ci</code> / <code>utf8mb4</code>) || leave as set
+|}
+The other fields (timeouts, timezone, DB Date Time, DB Select Limit, DB Schema, Unique ID) already hold the right values for the database type. Leave them alone.
+To start from a blank connection instead, click '''Add DB Connection'''. '''Delete DB Connection''' removes the selected one.
+== Test the connection ==
+Click '''Connect / Check DB'''. One of three things happens:
+* '''Connected, and the ''Version Information'' panel shows ''Actual Schema Version'' as <code>-1</code>.''' Correct for a brand-new empty database: it means Setup4j reached the database and found no Commander4j tables yet. Go to the next section.
+* '''Connected, and the actual and required versions match, with green ticks.''' The database is already set up for this version of Commander4j. Click '''Save Configuration''' and you are done.
+* '''An error message.''' The status bar at the bottom explains what went wrong. Common causes: TCP/IP not enabled in SQL Server, wrong server or instance name, wrong password, or SQL Server still in Windows-only authentication mode. See [[Install Database]] and [[Install Guide#If something goes wrong]].
+== Create or upgrade the tables ==
+[[file:Commander4j upgrade 6b.png|500px]]
+When the actual version is lower than the required version, the '''AUTO Update DB''' button becomes available. Click it. Setup4j creates or upgrades every table, view and function, then loads the standard data (menus, permissions, language text, example records).
+On an empty database this takes several minutes, and the progress bar at the bottom moves slowly at first. Let it finish. When it does, both versions match and show green ticks.
+If the update stops with an error, it is almost always a permissions problem: the database user is not allowed to create tables or views. Fix the permissions as described in [[Install Database]], drop any tables that were created, and run '''AUTO Update DB''' again.
+== Save ==
+Click '''Save Configuration'''. Setup4j writes <code>hosts.xml</code> and you can close it.
+Tidy-up, once your own connection works: select each example connection and either untick '''Enabled''' (it stays in the file but users no longer see it) or click '''Delete DB Connection'''.
+'''Next step:''' [[First Login]].
+== Other things Setup4j can do ==
+* '''Enable Splash Screen''' and '''Single Instance''' control how the application starts. Single Instance stops a user opening Commander4j twice on the same PC.
+* '''Protect Configuration with Password''' stops users opening Setup4j and changing connections.
+* '''Assign to Service''' links a connection to the Windows interface service on a Full install. See [[Install Interface Services]].
+* '''DB Schema Report''' lists the tables and columns in the connected database.
+* '''Update Mode''', '''URL App Update''' and '''URL Hosts Update''' configure automatic update checks. They are optional and can be left alone.
+* '''Open Hosts File''' switches to a different <code>hosts.xml</code>, for example when maintaining connections for a Tomcat server.
+[[Category: Commander4j]]