Standard Installing

The following example will install the server in /opt/odilon and data directories in /opt/odilon-data.

Installation

Download the Odilon server package:

sudo wget https://odilon.io/resources/odilon-2.1-installer.tar.gz

Extract the package and run the installation script:

sudo tar xvf odilon-2.1-installer.tar.gz
cd odilon-installer-2.1
sudo ./install-odilon.sh

Create the data directory if it does not exist:

sudo mkdir -p /opt/odilon-data
sudo chown -R odilon:odilon /opt/odilon-data
sudo chmod u+rwx /opt/odilon-data
sudo chmod og-rwx /opt/odilon-data

After executing the install-odilon.sh script, the server is installed and registered as a systemd service. The next step is to edit the configuration file odilon.properties created in /etc/odilon.

Configuration

Odilon configuration file is /etc/odilon/odilon.properties. This is where you can set up server port and credentials (port, accessKey, secretKey), data storage (RAID level, data storage directories), and other parameters.

accessKey and secretKey are the server credentials, required to interact via the Java SDK or REST API.

The redundancy level must be RAID 0, RAID 1, or ErasureCoding. You must configure data storage directories (at least 1 for RAID 0, at least 2 for RAID 1, at least 3 for ErasureCoding).

A bare minimum odilon.properties file:

server.port=9234
accessKey=odilon
secretKey=odilon
redundancyLevel=RAID 0
dataStorage=/opt/odilon-data/drive0

These settings are sufficient to start the server. In most cases, no additional configuration is required. Encryption and version control are disabled by default, but they can be enabled in the future without affecting the existing data.

For detailed instructions:

Data Replication

Encryption

Version Control

Master-Standby replication

HTTPS

The script ./bin/config.sh contains the Java Virtual Machine (JVM) configuration. In most cases, you do not need to modify it. However, you may need to set the JAVA_HOME variable to the Java 17+ installation directory on your server or adjust other JVM parameters as needed.

Start and stop the server

After editing /etc/odilon/odilon.properties to set up the server (minimally port, accessKey, secretKey, redundancyLevel and dataStorage) the server is ready to run.

The bin/service.sh script works on both Linux and Mac. It starts the service, waits for it to come up, prints the service state and calls the info API.

# Start — registers and starts the service, then prints status + API response
sudo /opt/odilon/bin/service.sh start

# Stop
sudo /opt/odilon/bin/service.sh stop

# Restart
sudo /opt/odilon/bin/service.sh restart

# Status only (no sudo needed)
/opt/odilon/bin/service.sh status

The script self-orients from its location — no arguments needed to identify the instance.
Logs are written to /opt/odilon/logs/.
If there are errors you can check startup.log and odilon.log there.

You can also use systemctl directly:

# start
sudo systemctl start odilon

# stop
sudo systemctl stop odilon

# status
sudo systemctl status odilon

# API check
curl -u odilon:odilon http://localhost:9234/info

Odilon Server comes with an embedded web server. Point your browser to http://127.0.0.1:9234/info to confirm the server started successfully.

Updating Odilon version

The installer automatically detects an existing installation and runs in upgrade mode: it stops the service, takes a rollback snapshot of the current binaries, replaces only the application files, and restarts. Your configuration in /etc/odilon and all stored objects are never touched.

Download the new package, extract it and run the installer with the same parameters used at install time. For a default installation (no custom flags) this is all you need:

# download the new version
sudo wget http://odilon.io/resources/odilon-server-2.1.tar.gz

# extract
sudo tar xvf odilon-server-2.1.tar.gz
cd odilon-server-2.1

# upgrade — installer detects /etc/odilon already exists and runs in upgrade mode
sudo ./install-odilon.sh

The installer will print a rollback command at the end in case anything goes wrong, for example:

# rollback to previous version if needed
sudo systemctl stop odilon
sudo cp -a /opt/odilon-backups/odilon/20260707_143000/. /opt/odilon/
sudo systemctl start odilon

Up to 3 rollback snapshots are kept automatically under /opt/odilon-backups/odilon/. Older ones are pruned when a new upgrade is run.

Migrating from a pre-2.x installation

Pre-2.x releases stored the configuration file inside the installation directory (/opt/odilon/config/odilon.properties) rather than in /etc/odilon/. The installer detects this automatically and runs in migrate mode:

Takes a full snapshot of the current installation (binaries and config) as a rollback safety net.
Copies your existing odilon.properties to /etc/odilon/odilon.properties — the canonical location going forward.
Renames the old config/ directory to config.migrated.<timestamp>/ — kept on disk until you remove it.
Reads the existing log directory from the running systemd unit and re-applies correct ownership — so a custom log path like /var/log/odilon is preserved and fixed.
Replaces the binaries and re-registers the service.

No manual steps are needed — just run the installer the same way as a normal upgrade:

cd odilon-installer-2.1
sudo ./install-odilon.sh

After migration, verify your settings in /etc/odilon/odilon.properties and remove the old backup directory when you are satisfied:

sudo rm -rf /opt/odilon/config.migrated.*

If your existing log directory had wrong permissions (causing the service to fail on start), the installer now fixes ownership automatically during migrate and upgrade. To fix it manually on a running server:

# replace /var/log/odilon with your actual log directory
sudo chown odilon:odilon /var/log/odilon
sudo chmod 750 /var/log/odilon
sudo systemctl restart odilon

Installing with custom parameters

If you need to run more than one Odilon instance on the same machine — for example a production server and a development server — each instance must have its own binaries directory, configuration directory, log directory, port and service name. All of these are set with flags passed to the installer.

Available flags:

sudo ./install-odilon.sh [OPTIONS]

  --name   NAME   Instance / service name       [default: odilon]
  --prefix DIR    Binary installation root      [default: /opt/<name>]
  --conf   DIR    Configuration directory       [default: /etc/<name>]
  --logs   DIR    Log directory                 [default: <prefix>/logs]
  --user   USER   System user to run as         [default: odilon]
  --port   PORT   HTTP listener port            [default: 9234]
  --dry-run       Preview actions without making changes

Example — two instances on the same machine:

# Production instance — default port 9234
sudo ./install-odilon.sh --name odilon-prod --port 9234

# Development / staging instance — different port and directories
sudo ./install-odilon.sh --name odilon-dev --port 9235

Each instance gets its own isolated set of directories and its own systemd service:

# odilon-prod
/opt/odilon-prod          ← binaries
/etc/odilon-prod          ← configuration  ← edit this
/opt/odilon-prod/logs     ← logs
odilon-prod               ← systemd service name

# odilon-dev
/opt/odilon-dev
/etc/odilon-dev
/opt/odilon-dev/logs
odilon-dev

Starting, stopping and checking status of a named instance:

# Start
sudo /opt/odilon-prod/bin/service.sh start
sudo /opt/odilon-dev/bin/service.sh start

# Status
/opt/odilon-prod/bin/service.sh status
/opt/odilon-dev/bin/service.sh status

# Or using systemctl directly
sudo systemctl start odilon-prod
sudo systemctl start odilon-dev

The bin/service.sh script self-orients from the directory it lives in — running /opt/odilon-prod/bin/service.sh start always manages the odilon-prod instance and nothing else.

To upgrade a named instance, extract the new package and re-run the installer with the same --name flag. The installer reads the parameters saved at install time from /etc/<name>/.odilon-instance, so only the name is needed:

cd odilon-installer-2.1
sudo ./install-odilon.sh --name odilon-prod
sudo ./install-odilon.sh --name odilon-dev

Resources

Installation, Configuration and Operation on Linux

Standard Installing

Installation

Configuration

Start and stop the server

Updating Odilon version

Migrating from a pre-2.x installation

Installing with custom parameters

Resources

Installation and configuration

Java application development

Server design and development

Videos