Installation

Before you start

• The package. iiziServer comes as one signed file, iiziServer-distribution-5.0.0.build.jar, on the download page. The same package installs a server and updates one.
• Java. A 64-bit Java 25 LTS or later, as a JDK: the package holds no Java of its own, and the Linux install script checks the package's signature with the JDK's jarsigner. Every launcher runs the Java named by the environment variable IIZI_JAVA when it is set, else a JDK in the installation's jdk directory, else java from the PATH.
• Ports. A new server answers on port 8080. Its database, Derby, runs as a database server on port 1527 of the same machine.
• ServerAdmin, the server's administration application, is at /app/com.iizix.serveradmin/ of the server.

Linux

The install script install-iiziServer.sh travels inside the package. It needs a Linux with systemd, unzip, the JDK above, and root rights (sudo). Take it out of the package and run it:

unzip -j iiziServer-distribution-5.0.0.build.jar bin/install-iiziServer.sh -d .
sudo sh install-iiziServer.sh --package iiziServer-distribution-5.0.0.build.jar --start

In order, the script:

1. creates the system user and group iizi, without a login shell – the server never runs as root;
2. checks the package's signature (signed by Mindus SARL) before anything is unpacked;
3. installs the server in /opt/iizi/iiziServer, owned by iizi and readable by nobody else;
4. writes the configuration conf/config-apps-only.iiziServer at the first install only – ServerAdmin's “Save configuration” writes it afterwards;
5. creates the systemd unit iiziServer.service and enables it, so that the server starts at boot;
6. with --start, starts the server and checks its first log lines.

Every step looks first and changes only what differs: the same command again prints NOTHING CHANGED. A failure prints _FAILURE_ with the reason. --dry-run prints what would be done and changes nothing; --help lists every option with its default. The ones most often needed:

The service, once installed:

sudo systemctl status iiziServer
journalctl -u iiziServer -f
sudo systemctl stop iiziServer
sudo systemctl start iiziServer

systemd starts the server again after a crash, after 10 seconds and at most five times in 300 seconds; a fatal error at the start is not retried and shows in systemctl status. The unit runs the server with limited rights: it can write /opt/iizi only, and bind ports below 1024 only when its configuration names one.

The installation keeps your data inside it: conf/ (the configuration), db/ (the database) and logs/. An update never touches them (below).

The first sign-in

1. At its first start the server gives the administrator iiziAdmin a generated password. It is shown once on the server's console and written to initial-admin-password.txt in the installation, readable by the server's account only:

   sudo cat /opt/iizi/iiziServer/initial-admin-password.txt

2. Open ServerAdmin: http://your-server:8080/app/com.iizix.serveradmin/, or the HTTPS address of your proxy.
3. Sign in as iiziAdmin with that password. ServerAdmin asks for a new password at once and then deletes the file, and asks for a real e-mail address. On an installed server every administrator is also asked for a second step.

What else a new database holds, and which of its accounts are disabled: Administrators and The seeded users. The license system is installed and does not enforce in 5.0: nothing is refused (Licensing).

Windows

On Windows the server runs as a Windows service, on x64 and ARM64.

1. Extract the package with a zip tool (a signed .jar file is a zip archive) into the folder that is to hold the server, for example C:\iiziServer. The path may contain spaces.
2. Open a command prompt as Administrator and install the service with is.bat, giving it the service name, SERVER, the folder of your JDK, the memory of the server in MB (at least 300) and the server's options:

   cd C:\iiziServer\bin\ntservice
   is.bat INSTALL "iizi Server" SERVER "C:\path\to\jdk-25" 1024 -config conf\config-apps-only.iiziServer -dbport 1527 -dbdir db -root root -app com.iizix.serveradmin -appjar apps\iiziServerAdmin.jar
   sc start iiziServer

The Windows service's name is the name you gave without its spaces, here iiziServer; it runs as LocalSystem. NTEVENTLOG after the memory (NTEVENTLOG INFO for the information lines too) writes the server's errors and warnings to the Windows Event Log. The service's own log is logs\iiziServerWrapper.log, the server's console logs\iiziServer-console.log.

• Stopping the service stops the server cleanly: the server closes its sessions and its database and ends; a server that has not ended within 95 seconds is ended at once. A service installed with the service programs of an earlier version ends the server at once: install it again (see After an update, below).
• Removing the service: is.bat UNINSTALL "iizi Server".
• After an update the service keeps the service programs of the previous version until it is installed again: stop it, run is.bat UNINSTALL and is.bat INSTALL with the same parameters, and start it.

The database

Derby: the default

The package ships Apache Derby, and a new server uses it with no setup: the server starts Derby on its own machine and keeps the data in db/. Derby is fine for development, trials and a single server.

PostgreSQL: for production

PostgreSQL is the recommended database for production, and it will be required for any setup with more than one server (in later releases). The package ships the PostgreSQL driver in jdbc-drivers/postgresql.

• The database is chosen in a file dbconf.properties, in the directory the server's option -dbconf directory names. jdbc-drivers/dbconf-example.properties lists every property, with a PostgreSQL example.
• The password is never written in that file. passwordSecret names its key in the server's secrets store, and iizi-secrets set (in bin/, run as the server's account) stores it there. classpath names the driver of jdbc-drivers/postgresql, as the example file shows:

  url=jdbc:postgresql://localhost:5432/iizi
  driverClassName=org.postgresql.Driver
  username=iizi
  password=
  passwordSecret=dbconf.myserver/password

• The server creates its tables (the schema IZS) in that database at its first start.

Moving a server from Derby to PostgreSQL

Only the users and the groups are carried over; nothing else is migrated. Two scripts do it, export-users-groups and import-users-groups:

1. Export the users and groups while the server still runs on Derby.
2. Configure the server for PostgreSQL and start it once, so that it creates its tables.
3. Import, first as a dry run that shows what would be added and changes nothing, then for real.

The import adds a group or a user only when its name is new, never changes an existing one, and gives a new user the groups it had. The former backup administrator iiziAdmin BACKUP and the 4.x group “Default All Apps (disabled!)” are left out. The export holds password hashes and e-mail addresses: delete it once the import is done.

Updates and going back

From ServerAdmin

1. Put the new package in the installation's updates directory, or upload it there.
2. In ServerAdmin's Dashboard, in the Server section, press Refresh, choose the package, and press “Restart and update”. ServerAdmin asks for your password again.

The server tells every Browser page and iiziRun connected to it, then restarts with the update. The package is verified before anything changes – its signature, a newer build, its content – and unpacked beside the installation. The previous installation is kept as one rollback copy, and a failed update is rolled back by itself. The result is in updates/update.result, every step in updates/update.log; the Dashboard shows the result at the next start.

What an update keeps

An update replaces the program and deletes the files the new version no longer has, except what the keep list conf/update-keep.lst names:

• kept as they are: conf/, db/, logs/, updates/, jdk/, bin/ntservice/ and root/.well-known/;
• merged: apps/ and demos/ – the shipped applications are updated, your own are kept.

Add a line for a directory of your own, for example pages under the web root; the file explains its three kinds of lines.

With the server stopped

The updater also runs from the command line, while the server is stopped – for example when ServerAdmin itself cannot be reached. On Linux, run it as the server's account, with the package in a place that account can read, such as the installation's updates directory:

sudo systemctl stop iiziServer
sudo -u iizi /opt/iizi/iiziServer/bin/iiziServer-update.sh /opt/iizi/iiziServer/updates/iiziServer-distribution-5.0.0.build.jar
sudo systemctl start iiziServer

On Windows it is bin\iiziServer-update.bat. Its exit code is 0 when the server was updated, 1 when nothing changed or the update was rolled back, 2 when the rollback failed too (the previous version is then in the rollback copy, iiziServer.rollback beside the installation).

Going back to the previous version

Stop the server and run the updater with the previous package and -allowDowngrade:

sudo -u iizi /opt/iizi/iiziServer/bin/iiziServer-update.sh previous-package.jar -allowDowngrade

The database is never rolled back: what the newer version changed in it stays changed. The rollback copy is replaced by every update: it is no backup.

Behind a reverse proxy

In production, put a reverse proxy in front of the server for HTTPS and your host names. Caddy, for example, terminates HTTPS, passes the host name through, adds the forwarded client address, and passes the server's WebSocket connections without a setting. The server then listens on the machine's own address only, and its port is not opened in the firewall.

1. Install the server for the proxy:

   sudo sh install-iiziServer.sh --package iiziServer-distribution-5.0.0.build.jar \
     --bind 127.0.0.1 --front-end --external-host app.example.com \
     --trusted-proxies "127.0.0.1, ::1" --start

   --front-end marks the port as secured by the proxy, with the external port 443. --trusted-proxies names the proxies whose forwarded client address the server believes: without it, every client counts as one source for the sign-in throttle and for geolocation, and the server says so at its start. The script writes these settings at the first install only; on a server already installed, set them in ServerAdmin (Server settings to review).
2. Point the proxy at the server. With Caddy, one site in its Caddyfile:

   app.example.com {
           reverse_proxy   127.0.0.1:8080
   }

   then sudo systemctl reload caddy.

The install script prints the proxy targets at its end; it never changes a proxy, a DNS name or a firewall. --admin-port N with --admin-external-host NAME adds a second port on which ServerAdmin alone is served, so that it can have a host name of its own.

Exit codes

The server's exit code tells its supervisor – the launcher bin/iiziServer.sh under systemd, or the Windows service – what to do next:

All codes, the Windows service and the logs: Server operations.

See also: Installing iiziGo · Upgrading from 4.x · System requirements

Back to IIZI Support