Prepare the environment

DocuWare Ivy needs a Linux host. This page gets you one, with Docker on it, and collects the few values the installation asks for. Then go to Install DocuWare Ivy.

Plan 45 minutes, most of it waiting for downloads.

Tip

Important

Who this is written for. Someone who administers Windows servers and is willing to run a handful of Linux commands from a list. Every command is given in full and every step says what you should see, so you do not need Linux experience to get through it.

Running it afterwards is a different matter. An installation that people rely on needs someone who can patch the Linux host, read a container log and take a backup. If that is not you, get whoever does it involved now rather than after the first incident.

DocuWare Ivy ships as a Linux container image and cannot run as a Windows container, so a Linux host is needed. How you provide it is your choice, and it depends on the infrastructure you already have:

  • a dedicated Linux host, physical or virtual, on whatever platform you run

  • a virtual machine on the Windows server that already runs DocuWare

Both are equally valid and everything after this page is the same either way. DocuWare and IIS stay where they are.

Checklist

Item

Value

Linux host

4 CPU, 8 GB RAM, 60 GB disk, Ubuntu Server 24.04. Dedicated machine, or a virtual machine on the server that already runs DocuWare

Fixed address for the Linux host

static IP or DHCP reservation

Free port on the Linux host

8080

Licence file

requested with the public host name on it, see below

Microsoft SQL Server

normally the one already serving DocuWare. An empty database for Ivy, a login that owns it, and port 1433 reachable from the Linux VM. See below

Mail server

SMTP host name, and the address mail should come from

Two passwords you choose

one for the Ivy administrator, one for Ivy's database login

The database

Ivy keeps everything in a relational database: tasks, cases, users, business data. It uses the customer's own Microsoft SQL Server — normally the instance DocuWare already runs — so no database ships with this installation and nobody has to look after an extra one.

Three things have to be true before the engine first starts. All three are done on the SQL Server, by whoever administers it:

What

Why

An empty database

e.g. AxonIvySystemDatabase. The engine creates its own tables inside it on first boot, but it does not create the database

A login that owns it

db_owner on that database and nothing else. Do not reuse sa: a compromised engine would otherwise reach every DocuWare database on the same instance

TCP/IP enabled, port 1433 reachable from the Linux VM

TCP/IP is switched off on a fresh SQL Server installation, and a firewall rule is usually needed as well
Tip

Important

The backup is theirs, not yours. Because the workflow state lives in that database, the backup that protects this installation is the SQL Server backup the DBA already takes. Ask for the Ivy database to be added to that schedule while you are asking for the database itself — it is much harder to arrange after an incident than before one.

Note
If there is no SQL Server, or you cannot have a login on it

Microsoft SQL Server Express is free and enough for a pilot, and the engine also supports other databases. Talk to DocuWare before choosing one: this guide, its checks and its error messages all assume SQL Server, so anything else means you are on your own with the parts that differ.

Ivy can also run without any database at all, in demo mode — and it does so silently, keeping nothing past a restart. That is not a deployment option; it is the failure this guide's check 2 exists to catch.

1 · Create the virtual machine

Note

Note

If you already have a Linux host with Docker, skip to Install DocuWare Ivy. Nothing in the product cares how that host came to exist, so if your infrastructure provides Linux machines another way, use that and rejoin at the install guide.

What follows is one of the two options above: a virtual machine on the Windows server, for sites that have no Linux platform to draw on. It describes Microsoft's product, so Microsoft's documentation is the authority: install the Hyper-V role and create a virtual switch. The commands below are for Windows Server; a Windows client edition uses different ones and only offers the NAT switch this page warns against.

Run these in an elevated PowerShell window on the Windows server. Or use Hyper-V Manager and the same values — the wizard asks for exactly these.

Check the Hyper-V role is there:

Get-WindowsFeature Hyper-V | Select-Object InstallState

If it is not installed: Install-WindowsFeature Hyper-V -IncludeManagementTools -Restart.

Pick the network switch:

Get-VMSwitch | Select-Object Name, SwitchType

You should see a list like this, and you want an External one:

Name           SwitchType
----           ----------
ivy-external   External
Tip

Important

Use an External switch. It puts the VM on your normal network, where it can have a fixed address and where IIS can reach it later. If you have none:

New-VMSwitch -Name ivy-external -NetAdapterName (Get-NetAdapter | Where-Object Status -eq 'Up' | Select-Object -First 1).Name -AllowManagementOS $true

The NAT "Default Switch" is wrong for an installation: the address changes and nothing outside the host can reach the VM.

Download Ubuntu Server (about 3 GB):

New-Item -ItemType Directory -Force -Path C:\iso | Out-Null
curl.exe -L -o C:\iso\ubuntu-24.04.4-live-server-amd64.iso https://releases.ubuntu.com/24.04/ubuntu-24.04.4-live-server-amd64.iso

If that address answers 404, Ubuntu has replaced the point release: open https://releases.ubuntu.com/24.04/, take the newest -live-server-amd64.iso and substitute the name in the commands below. Any 24.04 point release works.

Create and start the VM. Replace ivy-external with your switch name:

New-VM -Name ivy -Generation 2 -MemoryStartupBytes 8GB -NewVHDPath C:\Hyper-V\ivy\ivy.vhdx -NewVHDSizeBytes 60GB -SwitchName ivy-external
Set-VM -Name ivy -ProcessorCount 4 -AutomaticCheckpointsEnabled $false
Add-VMDvdDrive -VMName ivy -Path C:\iso\ubuntu-24.04.4-live-server-amd64.iso
Set-VMFirmware -VMName ivy -SecureBootTemplate MicrosoftUEFICertificateAuthority
Set-VMFirmware -VMName ivy -FirstBootDevice (Get-VMDvdDrive -VMName ivy)
Start-VM ivy
vmconnect.exe localhost ivy

You should see the Ubuntu installer in a console window.

2 · Install Ubuntu

Run through the installer as you normally would. Two things matter:

  • Tick Install OpenSSH server. Without it you cannot connect from Windows or copy files to the VM, which is how the rest of this works.

  • The user name you create is <your-user> in the installation guide.

Note
The other screens, if you want them listed

Screen

Choose

Installation type

Ubuntu Server, not "minimized"

Network

note the address it shows

Storage

Use an entire disk, then Done and Continue

Ubuntu Pro

Skip

Snaps

none

If the OpenSSH box was missed, install it afterwards in the VM console: sudo apt install -y openssh-server

Reboot when it asks, then log in at the console.

Give the VM a fixed address before anything points at it: a static address, or a DHCP reservation for its MAC. The IIS rule forwards to this address, and if it moves the installation breaks without saying so.

3 · Install Docker

Connect from Windows first — the rest of this page and the whole installation guide happen in that window:

Listing 1 On the Windows machine — the pattern
ssh <your-user>@<linux-host>

Anything in angle brackets is yours to replace, brackets included. The examples on this page and in the installation guide use the same two values: <your-user> is ivyadmin, <linux-host> is 192.168.10.20. So:

Listing 2 On the Windows machine — with values filled in
ssh ivyadmin@192.168.10.20

The first connection asks you to confirm a fingerprint — type yes — then the password. ssh is part of Windows and needs no installation.

Then, on the Linux host:

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo usermod -aG docker $USER

Log out and back in — type exit, then ssh in again. The group change only applies to a new session.

Confirm it works:

docker ps

You should see one line of column headings and nothing under it:

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
Tip

Important

Use docker ps, not docker --version. The version command passes even when Docker cannot be used, because it never contacts the Docker service. If docker ps says permission denied while trying to connect to the Docker daemon socket, the group change has not taken effect — log out and back in again.

4 · If you work through a jump host

Many administrators reach the DocuWare server over Remote Desktop, and then ssh from there. Copy and paste stops working somewhere along that chain, which makes an installation built on pasted commands painful.

Where it breaks

What to do

Remote Desktop to the Windows server

In the Remote Desktop client, Show Options → Local Resources, and make sure Clipboard is ticked before connecting

Nested Remote Desktop, a session inside a session

The clipboard usually survives one hop and not two. Open the guide in a browser on the innermost machine and copy there

PuTTY instead of Windows Terminal

A right-click pastes. Ctrl+V does nothing

Nothing works

Save the commands to a file, copy the file to the server, and use it there. The commands are also in the downloadable files this guide links to

5 · Request the licence, with the right name on it

Do this early: it is the item with a waiting time, and the one that most often holds an installation up.

Request it from the DocuWare Ivy team, or through DocuWare support. Tell them the public host name users will type, because the licence is issued for that name.

Also collect, while you are waiting:

  • The mail server: SMTP host name and the address notifications should come from. Without it the portal's password reset fails and no notification mail ever arrives, and nothing warns you at install time.

  • Two passwords you choose: one for the Ivy administrator, one for Ivy's own database. You type both into files during the installation.

Next

Install DocuWare Ivy. It assumes exactly what this page produced: a Linux host with Docker, reachable over ssh from Windows.