How to Install eDirectory Using the Ansible Installer

Introduction

The eDirectory Ansible Installer is a technical installation tool designed to automate the setup of a fresh self-hosted eDirectory environment.

This installer helps configure the main server requirements needed by eDirectory, including Apache, PHP, MySQL/MariaDB, Elasticsearch, the eDirectory package download, and the initial system configuration.

The Ansible Installer is intended for technical users, system administrators, and customers with a source license who want to install a fresh new eDirectory instance on their own server.

Important Note: This process is intended for a fresh installation of eDirectory. It is not the same as migrating an existing live website with content, files, media, users, listings, and database records.

Fresh Installation vs. Website Migration

Before using the Ansible Installer, it is important to understand the difference between a fresh installation and a migration.

A fresh installation creates a new eDirectory environment using a clean server and a new database structure. This is useful when installing the software from the beginning.

A migration transfers an existing eDirectory website from one hosting environment to another. A migration requires moving both the application files and the database content from the current website.

The Ansible Installer is designed for fresh installations. If your goal is to move an existing eDirectory website to a new server, please contact our support team so our Infrastructure team can review the migration process.

What the Ansible Installer Does

The Ansible Installer automates the setup of the main services required by eDirectory.

The playbook installs and configures:

Apache
PHP and required extensions
MySQL/MariaDB
Database credentials
Elasticsearch
eDirectory package download
Application configuration
Initial database configuration
Required system environment
Initial eDirectory setup

The installer was created to reduce the need for manual server configuration and to avoid inconsistencies that may happen when installing each dependency separately.

Requirements

Before starting, make sure you have:

A clean Linux server
Ubuntu 22.04 or Ubuntu 24.04
Root or sudo access
Ansible installed on the machine that will execute the playbook
A valid eDirectory package version
The download password required to retrieve the eDirectory package
A domain or subdomain that will be used for the installation

Important Note: Do not run the installer on a server that already hosts other websites, applications, custom databases, or conflicting server configurations unless you fully understand the impact.

Installing Ansible

On Ubuntu/Debian-based distributions, install Ansible using:

apt update
apt install -y ansible

After installing Ansible, you can confirm it is available by running:

ansible --version

Downloading the Installer

The eDirectory Ansible Installer package is provided by the eDirectory support or infrastructure team when applicable.

After receiving the installer package, access your server and download/extract it in the recommended directory.

Example:

cd /root
wget [installer-download-url]
tar -zxvf edirectory-ansible-installer.tar.gz
cd edirectory-ansible-installer

Replace [installer-download-url] with the download link provided by the eDirectory team.

For security reasons, do not share installer credentials, package passwords, or download URLs publicly. You may email our Support team to request the raw copy of the source code files at support@edirectory.com.

Configuring the vars.yml File

Before running the playbook, edit the vars.yml file and fill in the required variables.

Example:

domain: domain.com
mysql_root_pass: mysqlrootpassword
db_prefix: prefix
db_pass: edirectorydatabasepassword
language: en
locale: en_us
edirectory_version: 14.1.00
download_pass: downloadpassword

Variables Description

Variable	Description
`domain`	Domain used for the eDirectory installation. Do not include `http://` or `https://` .
`mysql_root_pass`	Root password that will be configured for the database service.
`db_prefix`	Prefix used for the eDirectory database names. Use only letters and numbers.
`db_pass`	Password used by the eDirectory database user.
`language`	Default system language.
`locale`	Default system locale.
`edirectory_version`	eDirectory package version that will be downloaded and installed.
`download_pass`	Password used to download the eDirectory package.

Important Configuration Rules

When editing vars.yml , review the following rules carefully:

The domain value must not include http:// or https:// .
The domain should be a valid domain or subdomain.
The db_prefix should contain only letters and numbers.
The language and locale values must match the supported options in the installer.
The edirectory_version must match the package version provided by eDirectory.
The download_pass must be valid for the selected package version.

If any required variable is missing or incorrectly formatted, the installer may stop during validation.

Running the Playbook

After configuring the vars.yml file, run:

ansible-playbook playbook.yml

The installation process may take several minutes depending on the server performance and network speed.

During execution, the playbook will install the required packages, configure services, download the eDirectory package, configure the environment, and complete the initial installation.

Domain and DNS Requirement

After the playbook finishes, you can test the site in your browser. However, the domain must already be pointed to the server’s IP address.

Before testing the website, confirm that:

The domain or subdomain has an A record pointing to the server IP.
DNS propagation has completed.
The domain in DNS matches the domain configured in vars.yml .
There are no conflicting DNS records or redirects.
The server firewall allows web traffic.

Accessing the Site Manager

After the installation is complete, the Site Manager area should be available at:

http://yourdomain.com/sitemgr

Replace yourdomain.com with the domain configured in your vars.yml file.

Basic Verification Commands

You can use the commands below to check the main services.

Check Apache:

systemctl status apache2

Check database service:

systemctl status mariadb

Check Elasticsearch:

systemctl status elasticsearch

Check if Elasticsearch responds locally:

curl http://localhost:9200

Check the cron jobs created for the web server user:

crontab -u www-data -l

Troubleshooting

The playbook fails during validation

Review the values entered in vars.yml .

Common causes include:

Missing required variable
Domain includes http:// or https://
Invalid domain format
Database prefix contains special characters
Invalid language value
Invalid locale value
Incorrect package version
Incorrect download password

The package cannot be downloaded

Confirm that:

The server has internet access.
The edirectory_version is correct.
The download_pass is correct.
The download URL is still valid.
There are no firewall restrictions blocking the request.

The website does not load after installation

Check if the domain is pointed to the correct server IP address.

Also confirm that Apache is running:

systemctl status apache2

If DNS is still propagating, the installation may be complete even though the domain does not load yet.

The Site Manager area does not load

Confirm that you are accessing the correct URL:

http://yourdomain.com/sitemgr

Also confirm that the domain used in the browser is the same domain configured in vars.yml .

Elasticsearch is not working

Check the Elasticsearch service:

systemctl status elasticsearch

If needed, restart it:

systemctl restart elasticsearch

Then test again:

curl http://localhost:9200

Cron jobs are missing

Check the cron list for the web server user:

crontab -u www-data -l

If the cron jobs are not listed, the playbook may not have completed successfully.

The domain points to the wrong location

Review the domain DNS configuration and confirm that the A record points to the correct server IP address.

If using a DNS proxy or CDN, temporarily disabling the proxy may help confirm whether the server is responding correctly.

Important Notes About Unsupported Setups

The Ansible Installer is intended for standard self-hosted installations on supported Ubuntu servers.

The following scenarios are not covered by this installer:

Migrating an existing live website
Installing eDirectory on a server with existing applications
Installing eDirectory inside Docker or containerized environments
Using PostgreSQL instead of MySQL/MariaDB
Splitting the application, database, and media files across multiple servers
Installing unsupported PHP, database, or Elasticsearch versions
Replacing the standard installation architecture with a custom infrastructure

Custom infrastructure scenarios may require additional planning outside the standard support scope.

Security Recommendations

After installation, we recommend the following:

Change the default Site Manager password immediately.
Store database passwords securely.
Do not share package download credentials publicly.
Restrict SSH access to authorized users only.
Review firewall rules.
Enable HTTPS/SSL before using the site in production.
Keep server access credentials secure.
Avoid using overly permissive file permissions.

Conclusion

The eDirectory Ansible Installer provides a simpler and more reliable way to perform a fresh self-hosted installation of eDirectory. It automates the installation of the main server requirements, including Apache, PHP, MySQL/MariaDB, Elasticsearch, the eDirectory package, and the initial system configuration.

Before running the installer, make sure you are using a clean supported Ubuntu server, that all required variables are correctly configured in vars.yml , and that your domain is pointed to the server’s IP address.

For existing live websites, the Ansible Installer should not be treated as a migration tool. If you need to move an existing eDirectory website to another server, contact eDirectory support so the migration can be reviewed properly.