iObservatory Boilerplate Stack

A Docker-based boilerplate for building data-driven Observatory platforms.

The stack combines open-source services for knowledge management, data integration, databases, and data storage. It is designed as a generic starting point that can be adapted to different Observatory use cases, domains, organisations, and data infrastructures.

The platform is modular: individual services can be configured, extended, replaced, or removed depending on the needs of the deployment.

⚠️ This repository is a template, not a plug-and-play application.

The first installation automatically creates environment files, generates credentials, installs configured extensions, builds the Docker stack, and initialises MediaWiki. Deployment-specific configuration may still be required.

---

🏗️ Architecture

See ARCHITECTURE.md for a detailed overview of the stack architecture, services, and components.

---

🧩 Components

See SERVICE.md for a description of the individual services and their roles in the stack.

---

🚀 Installation

See SETUP.md for a step-by-step installation guide.

---

🐳 Docker Lifecycle

The Makefile provides shortcuts around Docker Compose.

Start

make up

Starts all services in the background.

Stop

make down

Stops and removes the Compose containers.

Restart

make restart

Restarts the running services.

Build

make build

Builds the Docker images.

Rebuild without cache

make rebuild

Useful after changes to Dockerfiles or dependencies.

Pull images

make pull

Pulls the latest configured Docker images.

Status

make status

Displays the current container status.

Logs

make logs

Follows the latest container logs.

---

🔄 Maintenance

After the initial installation, do not run make install again.

The normal maintenance command is:

make update

The update pipeline is designed for an already-installed platform.

It can perform:

Pull latest images
       ↓
Synchronise extensions
       ↓
Rebuild containers
       ↓
Start services
       ↓
Update Composer dependencies
       ↓
Update MediaWiki database

For more controlled maintenance, the individual commands can be executed separately.

For example:

make extensions
make composer
make mediawiki-update

---

🛠️ MediaWiki Maintenance

Update the database

make mediawiki-update

Runs the MediaWiki database update process.

Open a MediaWiki shell

make shell

This opens a shell inside the MediaWiki container.

This is useful for debugging and running MediaWiki commands manually.

---

💾 Database Backups

See BACKUP.md for instructions on creating and managing MariaDB/PostgreSQL backups.

---

🌐 Accessing the Platform

The exact URLs depend on the values configured in the root .env and Docker Compose configuration.

The default services include:

Service	Default port	Purpose
MediaWiki	8080	Knowledge and ontology management
Apache Hop Web	8081	Data integration and ETL
MariaDB	3306	MediaWiki database
PostgreSQL	Configured in Compose	Relational data
MinIO	Configured in Compose	Object storage

After installation, the generated:

connection-info.txt

contains the configured access information.

You can inspect it with:

cat connection-info.txt

---

🔐 Security

This repository contains infrastructure capable of handling potentially sensitive data.

Never commit:

.env
connection-info.txt

or other files containing credentials.

Only commit the corresponding:

.env.example

templates.

The .gitignore should therefore exclude environment files, generated credentials, database backups, and other deployment-specific artefacts.

---

📋 Makefile Command Reference

Run:

make help

to display the commands available in the current version of the platform.

The main commands are:

First installation

make install

Complete first-time installation.

make init-env

Create missing .env files.

make credentials

Generate missing security credentials.

You should only run the make install command as it performs the initial setup of the platform and call the other commands. After that, use make update for maintenance.

MediaWiki

make extensions
make composer-install
make composer
make mediawiki-install
make mediawiki-update

Docker

make build
make rebuild
make up
make down
make restart
make pull
make status
make logs

Maintenance

make update
make backup-mariadb
make shell

---

🧭 Typical Workflows

First deployment

git clone <repository-url>
cd <repository-directory>

make init-env
# Review and configure .env files

make install

---

Everyday use

make up

Then access the required services.

When finished:

make down

---

Adding a MediaWiki extension

# Edit services/mediawiki/extensions.config

make extensions
make composer              # if required
make mediawiki-update     # if required

---

Updating the platform

make update

---

Troubleshooting

Check service status:

make status

View logs:

make logs

Open the MediaWiki container:

make shell

Rebuild the Docker images:

make rebuild

---

📐 Design Philosophy

iObservatory is intended to provide a reusable technical foundation, rather than a fixed application.

The stack therefore follows several principles:

• Modularity — services can be added, removed, or replaced.
• Extensibility — MediaWiki extensions and data-processing pipelines can be added independently.
• Separation of concerns — knowledge management, relational storage, ETL, and object storage are provided by separate services.
• Automation — repetitive deployment and maintenance tasks are exposed through the Makefile.
• Configuration through environment files — deployment-specific values remain outside the application template.
• Reproducibility — .env.example, Docker Compose, extension configuration, and Make targets provide a repeatable deployment process.
• Privacy-conscious deployment — the stack is designed to support self-hosted infrastructure and local control of data.

The objective is to provide a foundation on which different Observatory platforms can be developed without requiring the underlying deployment architecture to be redesigned from scratch.