Install DocuWare Ivy

The image carries the DocuWare-branded Portal already. There is nothing to deploy by hand.

Start from Prepare the environment: this page assumes a Linux host with Docker, reachable over ssh from Windows.

Plan 30 minutes. Most of the work is on your Windows machine; the Linux part is four commands.

The whole thing, in order

What

Where

1

Choose the image

a decision, no commands

2

Fill in two files

Windows, in Notepad

3

Copy them to the Linux host

Windows, scp

4

Start

Linux, docker compose up -d

5

Open the portal

Windows, through an SSH tunnel

6

Run four checks

Linux. Do not skip

7

Create the first user

Engine Cockpit

8

Confirm mail works

browser

Three things fail quietly, and all three have a check in this guide: the licence, the mail server, and using the wrong image.

How to read the commands

Anything in angle brackets is yours to replace, brackets included. The examples all use the same three values:

Placeholder

Example

What it is

<your-user>

ivyadmin

the user you created on the Linux host

<linux-host>

192.168.10.20

its address

<path-from-pwd>

/home/ivyadmin/ivy

the folder path printed in step 3

Every command block says which machine it belongs to. Unmarked ones are on the Linux host.

Most Linux commands print nothing when they work. An empty response is the good outcome.

1 · Choose the image

Image

Use it when

docuwarepublic.azurecr.io/ivy/project-ivy

this one, unless you know otherwise. Search works with no setup

docuwarepublic.azurecr.io/ivy/project-ivy-slim

only if you already run an OpenSearch cluster and want the engine to use it

It is the default in the Compose file, so there is nothing to change.

Which tag to use is a separate question. There are different tags for different release cycles, so pick the one that fits your context, or use the one DocuWare gave you. The bundle ships with a working default, and the DocuWare Ivy team can tell you which tag is right for an installation.

Tip

Important

Pin a version, not latest. Tags like 14.0.0, 14.0 and latest move to the newest release, so afterwards nobody can say which build is running — the first thing DocuWare asks when you report a problem.

If you choose -slim, point the engine at your OpenSearch server in config/ivy.yaml, or search stays broken:

SearchEngine:
  ExternalServer:
    Url: "http://my-opensearch-server"

2 · Fill in two files

On your Windows machine, in Notepad, before anything is copied. Editing files inside a Linux shell is the part people find hardest, and this way you never have to.

Make a folder, for example C:\ivy-install, and extract the installation bundle into it:

docuware-ivy-onprem.zip

C:\ivy-install\
├── docker-compose.yml     leave as delivered
├── compose.sso.yml        leave as delivered
├── env.example            edit, then save as .env
└── config\
    ├── ivy.yaml           edit
    ├── licence.lic        your licence file, renamed
    ├── context.xml        leave as delivered
    ├── log4j2.xml         leave as delivered
    ├── mode.sso.env       leave as delivered
    ├── mode.entra.env     leave as delivered
    └── proxy\
        ├── appsettings.sso.json      leave as delivered
        └── appsettings.entra.json    leave as delivered

Two files are edited, env.example and config\ivy.yaml, and the licence is yours to put in place. Everything else arrives ready to use and is never edited: an installation is described by .env.

The files most installations touch are published on their own as well, if you would rather take them one at a time: docker-compose.yml, env.example and ivy.yaml.

env.example — five values

Line

Replace with

IVY_MSSQL_URL=jdbc:sqlserver://sql.customer.example:1433;databaseName=AxonIvySystemDatabase

your SQL Server and the database you created for Ivy. Keep the shape exactly: semicolons, and the database as databaseName=

IVY_MSSQL_USER=ivy

the login that owns that database

IVY_MSSQL_PASSWORD=change-me-before-first-start

that login's password. Letters and digits only — see the warning below

IVY_IMAGE_TAG=latest

the tag for your release cycle, never latest — see Choose the image

TZ=Europe/Berlin

your time zone as Region/City. It sets log timestamps and task due dates

One more line is worth knowing about even though most installations leave it alone:

Line

When to change it

IVY_HTTP_PORT=8080

when something on this host already listens on 8080. It is the only port the installation publishes, so this is the number every command on this page and the IIS rule both refer to. Change it here rather than in the Compose file, and remember that the rest of this page writes 8080 literally — substitute your value
Note

Note

Nothing else in .env.example needs an answer. Every remaining line either has a working default or is an example left in place to show the shape, and the comments say which is which.

env.example open in Notepad, showing comment lines and the lines that are not comments

Figure 2 Most of the file is comments, which start with #. You are looking for the handful of lines that are not.

Tip

Important

The database, the login and its ownership are made on the SQL Server, not here — see the prerequisites. The engine creates its own tables inside the database on first boot, but it does not create the database, and it cannot create the login.

Save it, and leave the name as env.example — step 3 renames it on the way.

Note
Two settings some installations need

Both are in the file, commented out.

IVY_MSSQL_TRUST_CERT is true by default, which is what a SQL Server using its own generated certificate needs. Set it to false only once the server has a certificate the Linux host trusts.

If the SQL Server runs on this same Linux host, use host.docker.internal as the host name in IVY_MSSQL_URL. The Compose file already maps that name.

config\ivy.yaml — two values

The administrator password. Find this line and replace only REPLACE-THIS-BEFORE-FIRST-START:

Listing 3 as shipped
Administrators:
  admin:
    Password: "${hash:REPLACE-THIS-BEFORE-FIRST-START}"
Listing 4 after your edit
Administrators:
  admin:
    Password: "${hash:MyChosenPassword123}"

Keep the quotation marks, ${hash: and the closing }.

config/ivy.yaml open in Notepad with the Administrators block showing the placeholder password

Figure 3 The Administrators block is the first thing to change.

The mail server. Further down, every line of the mail block starts with #, which means "ignore this line". Remove the # and the space after it from the lines you need:

Listing 5 as shipped, inactive
# EMail:
#   Server:
#     Host: smtp.customer.example
#     Port: 587
#     MailAddress: portal@customer.example
#     EncryptionMethod: START_TLS
Listing 6 after your edit, active
EMail:
  Server:
    Host: smtp.mycompany.example
    Port: 587
    MailAddress: ivy-portal@mycompany.example
    EncryptionMethod: START_TLS
Tip

Important

Indentation and key names have to be exact

  • Keep the leading spaces as shown, and use spaces, never tabs. A tab stops the engine from starting.

  • A key at the wrong indentation is worse: the engine starts healthy and the setting simply does nothing.

  • The block is EMail, not Mail, and the sender is Server.MailAddress, not From. A wrong key name changes nothing and reports nothing.

Step 8 is the check that catches a mail block which looks right and is not. Until mail works, the portal's password reset fails and notification mails never arrive.

3 · Copy them to the Linux host

On the Linux host, create the destination and print its path:

mkdir -p ~/ivy/config && cd ~/ivy && pwd

You should see the full path, for example /home/ivyadmin/ivy. The next commands need it, spelled out in full.

In a second PowerShell window on Windows, four copies:

Listing 7 On your Windows machine — the pattern
cd C:\ivy-install
scp docker-compose.yml <your-user>@<linux-host>:<path-from-pwd>/
scp env.example        <your-user>@<linux-host>:<path-from-pwd>/.env
scp config\ivy.yaml    <your-user>@<linux-host>:<path-from-pwd>/config/
scp config\licence.lic <your-user>@<linux-host>:<path-from-pwd>/config/
Listing 8 On your Windows machine — with values filled in
cd C:\ivy-install
scp docker-compose.yml ivyadmin@192.168.10.20:/home/ivyadmin/ivy/
scp env.example        ivyadmin@192.168.10.20:/home/ivyadmin/ivy/.env
scp config\ivy.yaml    ivyadmin@192.168.10.20:/home/ivyadmin/ivy/config/
scp config\licence.lic ivyadmin@192.168.10.20:/home/ivyadmin/ivy/config/

Read a line as copy this local file, to that user, at that machine, into that folder. The second one renames env.example to .env on the way, which is the name Compose looks for.

Use the full path rather than ~, and run these in PowerShell rather than Git Bash.

Back on the Linux host, clean up Windows line endings and confirm all four arrived:

cd ~/ivy
sed -i 's/\r$//' .env config/ivy.yaml
ls -l docker-compose.yml .env config/ivy.yaml config/licence.lic

You should see four lines, none of them zero bytes.

Then the log folder, which the engine writes to as uid 1000:

mkdir -p logs && sudo chown -R 1000:1000 logs config

Both print nothing. That is the expected outcome.

Tip

Important

config/licence.lic has to be a file before the first start. If it is missing, Docker creates a directory with that name and the engine restarts in a loop.

4 · Start

docker compose up -d

The first run downloads the image. You should see it end like this:

[+] Running 5/5
 ✔ Network dwportal_ivy-net    Created
 ✔ Volume dwportal_ivy-config  Created
 ✔ Volume dwportal_ivy-apps    Created
 ✔ Volume dwportal_ivy-data    Created
 ✔ Container dwportal-ivy      Started

Then watch the engine boot — two to four minutes:

docker compose logs -f ivy

You are waiting for one line:

Axon Ivy Engine is running and ready to serve.

Press Ctrl+C when it appears. That stops the watching, not the engine.

Started means the container started, not that the engine is ready. If the log stops before that line, or the same messages repeat every few seconds, the engine is restarting in a loop — go to step 6, which names the cause.

5 · Open the portal

The Linux host has no browser. First confirm from the host itself:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/ivy/docuware/project-ivy/

You should see 200.

To see it in a browser, forward the port through ssh so that your browser addresses localhost:

Listing 9 On your Windows machine — the pattern
ssh -L 8080:localhost:8080 <your-user>@<linux-host>
Listing 10 On your Windows machine — with values filled in
ssh -L 8080:localhost:8080 ivyadmin@192.168.10.20

Leave that window open. Then, in the browser:

What

Address

Portal

http://localhost:8080/ivy/docuware/project-ivy/

Engine Cockpit

http://localhost:8080/ivy/system/
The DocuWare Ivy portal login page with the DocuWare logo, username and password fields and a blue Login button

Figure 4 The portal, with its styling. Plain black-on-white text instead means the page arrived and its stylesheets did not.

Tip

Important

Do not try to log in yet — there is no user. A licensed installation deploys none, on purpose. An empty user list is a sign the licence is working. Step 7 creates the first one.

The engine start page showing one application tile named project-ivy

Figure 5 At the Cockpit address, the tile named project-ivy is the branded portal the image deployed by itself.

Note

Note

Use localhost, not the host's IP address: the licence covers localhost, 127.0.0.1 and ::1 unconditionally, and any other name answers 400 until it is on the licence. Users will arrive through IIS on a licensed public name — the next guide.

You will need the host's address for the IIS rule later: hostname -I prints it, and the first one is the address on your network.

6 · Four checks

The engine reports itself healthy in situations where the installation is unusable. Run all four, and again after every upgrade.

Tip

Important

Every new connection starts in your home folder. First thing to type:

cd ~/ivy

Without it, docker compose answers no configuration file provided: not found, which means only that you are in the wrong folder.

Check 1 — the right image, the container healthy

docker compose ps

You should see one line, Up and (healthy), with the image you chose:

NAME           IMAGE                                                STATUS
dwportal-ivy   docuwarepublic.azurecr.io/ivy/project-ivy:<your tag>  Up 4 minutes (healthy)

Check 2 — a real database, not demo mode

grep -E 'System Database Manager|Creating system database' logs/console.log

You should see your SQL Server named:

Creating system database 'jdbc:sqlserver://sql.customer.example:1433;databaseName=AxonIvySystemDatabase'.
System database was successfully created.
[ 22%] System Database Manager (Microsoft SQL Server) started [308ms]

The first two lines appear only on the very first start — that is the engine creating its tables inside the database you made for it.

Note
If the line names something else

The line says

Meaning

(Microsoft SQL Server)

what this guide sets up

(PostgreSQL)

an older installation. It works, but the database is then one more thing you own; see Upgrading

(Hypersonic SQL Db)

demo mode, nothing is kept — see the licence entries in step 10
The Engine Cockpit System Database page with a green Connected bar and the database and driver named

Figure 6 The same answer in the Engine Cockpit, for later: System ‣ System Database.

Check 3 — the application deployed

docker compose exec ivy sh -c 'find /ivy/deploy -name "*.deploymentLog" -exec grep -E "Convert project|reached state" {} +'

You should see exactly one line:

Info: Application has reached state 'STARTED'
Note
If there is a second line

A Convert project in version … to latest … line means the application was built for a different engine than the one in this image. It still deploys. Report the image version to DocuWare.

Check 4 — the portal answers

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/ivy/docuware/project-ivy/

You should see 200. 000 means nothing answered — still booting, or stopped.

7 · Create the first user

With the tunnel from step 5 open, go to http://localhost:8080/ivy/system/ and choose Engine Cockpit from the top menu. Log in as admin with the password from step 2.

The Engine Cockpit sign-in form with an Axon Ivy logo and a Sign In button

Figure 7 This looks nothing like the portal login, and that is correct: the administration interface is Axon Ivy's own and is not rebranded.

Note
If the administrator password is refused

The engine may have read the file before your change: docker compose restart ivy, wait a minute, try again.

If you left the placeholder in place, your password is literally REPLACE-THIS-BEFORE-FIRST-START. The engine hashes whatever stands inside ${hash:…}.

If you cannot remember what you typed, the file will not tell you — the engine replaced it with a hash. Set a new one: nano config/ivy.yaml, change the line, Ctrl+O, Ctrl+X, then docker compose restart ivy.

Then Security ‣ Users ‣ Add:

The Add new user dialog with fields Name, Full Name, E-Mail Address, Password and Confirm Password

Figure 8 Only Name is mandatory, and it is the name this person types to log in.

Log in to the portal at http://localhost:8080/ivy/docuware/project-ivy/ with that user.

The DocuWare Ivy portal dashboard after logging in, greeting the user by name

Figure 9 A finished installation. Currently, there are no tasks available is correct — nothing has created work yet.

Note
Where users normally come from

Creating them by hand is fine for the first one. In an installation they come from a security system: Active Directory, Microsoft Entra ID or DocuWare. Ready-made snippets are inside the container:

docker compose exec ivy ls /ivy/configuration/templates/

For Entra ID, the Entra guide covers the whole path, including how one sign-in can serve both DocuWare and DocuWare Ivy.

8 · Confirm mail works

Nothing so far has sent a mail, so nothing has tested the setting from step 2. The Engine Cockpit tests it in two clicks — do that rather than guessing.

  1. Open http://<linux-host>:8080/ivy/system/ and log in as the administrator from step 2.

  2. On the dashboard, read the Email panel. It shows the settings in force, which is the only reliable check that your edit was read:

    Field

    Not configured

    Configured

    Server

    empty

    smtp.mycompany.example

    Port

    -1

    587

    Mail address

    noreply@ivyserver.local

    your sender address

  3. Click Send Test Mail, fill in To and Subject, and click Send.

You should see Success, and the Log pane ending in:

MAIL FROM:<ivy-portal@mycompany.example>
250 2.1.0 Ok
RCPT TO:<you@mycompany.example>
250 2.1.5 Ok
...
250 2.0.0 Ok: queued as 6sfACmlcQ85eYIqf0KcIRd
DEBUG SMTP: message successfully delivered to mail server

The Log pane prints the whole SMTP conversation, so a refused sender, a failed login or a blocked port names itself there.

Note
If the test mail fails

  • The key names are wrong. It is EMail, not Mail, and Server.MailAddress, not From.

  • EncryptionMethod is missing. It defaults to NONE, and port 587 normally wants START_TLS.

  • The SMTP server does not relay for this host, or will not accept Server.MailAddress as a sender.

  • The server wants authentication: uncomment User and Password in the mail block.

  • Port 587 is blocked between the Linux host and the mail server.

After any change to config/ivy.yaml: docker compose restart ivy.

Once mail works, the portal's Forgot my password page works too. It answers "If this e-mail address is registered then we have sent a password recovery link to it" whether or not the address matched, so it is not a test of your mail settings — the Cockpit dialog above is.

9 · Upgrading

A new image appears every two to three weeks. Nothing updates itself.

Tip

Important

Have the database backed up first, by whoever backs up the SQL Server. The engine migrates its schema on the first boot of a new version, and going back to the old image does not undo that.

This is the one step here that is somebody else's job, and the one you cannot skip. Nothing in this folder can take that backup for you: the workflow state lives in the SQL Server database, not in a Docker volume.

Note
What the database backup does not contain

Settings made in the Engine Cockpit — application variables above all — are written to configuration/applications/ inside the ivy-config volume, not to the database. An upgrade keeps them, because the volume outlives the container. Two things do not:

  • docker compose down -v, which is why that command appears here only where starting over is the intention

  • moving the installation to another host, where the volume does not travel with the folder you copy

To take a copy:

docker run --rm -v dwportal_ivy-config:/c -v "$PWD:/out" alpine \
  tar czf /out/ivy-config.tgz -C /c .

The volume name carries COMPOSE_PROJECT_NAME from .env; docker volume ls shows the real one.

Set the new version in .env — nano .env — then:

docker compose pull ivy && docker compose up -d ivy && docker compose logs -f ivy

Afterwards re-run all four checks from step 6. An upgrade can change the answer to every one of them.

Note
Going back

Set the previous version in .env, run docker compose up -d ivy, and restore the database dump if the schema was already migrated. The volume name carries COMPOSE_PROJECT_NAME from .env (dwportal unless you changed it); docker volume ls shows the real names.

10 · When something is wrong

What you see

What to do

no configuration file provided: not found

Wrong folder. cd ~/ivy

permission denied from docker

The group change has not taken effect. Log out and back in

The engine restarts every few seconds

Usually the licence file. config/licence.lic must be a file: Docker creates a folder with that name if it is missing, and an empty or truncated file fails the same way. The engine log names it

Hypersonic SQL Db in check 2

No usable licence, so the engine is in demo mode and nothing is kept. Put config/licence.lic in place and restart

The engine starts healthy but a setting seems ignored

A key at the wrong indentation. logs/config.log prints each setting's full path — WebServer.IvyContextName is right, IvyContextName alone means it landed at the top level

The engine will not start after you edited ivy.yaml

Look for a tab character before anything else. Tabs are not allowed in YAML and the error does not mention them

The database login is refused

A $ in IVY_MSSQL_PASSWORD, or a Windows line ending. Use letters and digits, and run the sed line from step 3

000 from check 4

Nothing answered. Still booting, or stopped

Browser shows nothing, but check 4 says 200

The ssh -L tunnel is not open, or something else holds port 8080 on your Windows machine

HTTP 400 by IP address or host name

Expected. The licence covers localhost and the public names you requested, nothing else

Login failed in the portal

Right engine, spelling, password — in that order. Both are case-sensitive

"Exception while sending email to you"

The mail server is not set or not reachable. Step 8

The portal loads without styling

The page arrived and its stylesheets did not. Check the address, including the docuware segment

11 · Reporting a problem

Send these three outputs. They identify the build exactly.

docker image inspect $(docker compose config --images | grep project-ivy) \
  --format '{{index .RepoDigests 0}}{{"\n"}}{{json .Config.Labels}}'

grep -m2 -E 'Version 14|Axon Ivy Engine' logs/console.log

docker compose exec ivy sh -c 'find /ivy/deploy -name "*.deploymentLog" -exec head -40 {} +'

Plus logs/ivy.log and logs/console.log. To get them onto Windows:

Listing 11 On your Windows machine
scp ivyadmin@192.168.10.20:/home/ivyadmin/ivy/logs/*.log C:\ivy-install\