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:

# for RAID 1 or Erasure Coding create at least 2 or 3 directories respectively
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 launchd 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
# this directory must exist and be writable by the odilon service user
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 Mac and Linux. 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 launchctl directly:

# start
sudo launchctl bootstrap system /Library/LaunchDaemons/io.odilon.odilon.plist

# stop
sudo launchctl bootout system/io.odilon.odilon

# status
launchctl print system/io.odilon.odilon | grep "state\|exit code"

# 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-2.1-installer.tar.gz

# extract
sudo tar xvf odilon-2.1-installer.tar.gz
cd odilon-installer-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 launchctl bootout system/io.odilon.odilon
sudo cp -a /opt/odilon-backups/odilon/20260707_143000/. /opt/odilon/
sudo launchctl bootstrap system /Library/LaunchDaemons/io.odilon.odilon.plist

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/.

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

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

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.
Detects and preserves the existing log directory and re-applies correct ownership.
Replaces the binaries and re-registers the service.

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.*

Fixing the Library/ directory inside /opt/odilon

Pre-2.x installers set the odilon service user's home directory to /opt/odilon. macOS automatically creates a Library/ folder inside any user's home directory, which is why you may see it there. The 2.x installer corrects this automatically during upgrade or migrate — setting the home to /var/lib/odilon instead.

If you need to fix it manually on a running server:

# 1. Stop the service
sudo launchctl bootout system/io.odilon.odilon

# 2. Fix the service user home directory
sudo mkdir -p /var/lib/odilon
sudo dscl . -create /Users/odilon NFSHomeDirectory /var/lib/odilon
sudo chown odilon /var/lib/odilon
sudo chmod 700 /var/lib/odilon
sudo dscacheutil -flushcache

# 3. Remove the Library/ directory that macOS created in the wrong place
sudo rm -rf /opt/odilon/Library

# 4. Restart the service
sudo launchctl bootstrap system /Library/LaunchDaemons/io.odilon.odilon.plist

# 5. Verify
launchctl print system/io.odilon.odilon | grep "state\|exit code"

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 launchd service:

# odilon-prod
/opt/odilon-prod          ← binaries
/etc/odilon-prod          ← configuration  ← edit this
/opt/odilon-prod/logs     ← logs
io.odilon.odilon-prod     ← launchd label

# odilon-dev
/opt/odilon-dev
/etc/odilon-dev
/opt/odilon-dev/logs
io.odilon.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

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 Mac

Standard Installing

Installation

Configuration

Start and stop the server

Updating Odilon version

Migrating from a pre-2.x installation

Fixing the Library/ directory inside /opt/odilon

Installing with custom parameters

Resources

Installation and configuration

Java application development

Server design and development

Videos