Installation Guide

This guide covers all installation methods for OpenRegister, from the Nextcloud App Store to Docker development environments.

Prerequisites

System Requirements

Minimum Requirements:

PHP 8.1 or higher
Nextcloud 28 or higher
Database: PostgreSQL 12+ OR MariaDB 10.5+ / MySQL 8.0+
2GB RAM minimum (4GB+ recommended)
1GB disk space for the app

Recommended Setup:

PHP 8.2+
Nextcloud 31+
PostgreSQL 16+ with pgvector and pg_trgm extensions
8GB RAM
SSD storage

Required PHP Extensions

# Core extensions
php-curl
php-gd
php-json
php-mbstring
php-xml
php-zip

# Database extensions (choose one)
php-pgsql    # For PostgreSQL (recommended)
php-mysql    # For MariaDB/MySQL

Installation Methods

Method 1: Nextcloud App Store (Recommended for Production)

The easiest way to install OpenRegister is directly from the Nextcloud App Store.

Open Nextcloud:
- Log in as an administrator
- Navigate to Settings → Apps
Search and Install:
- Click on "Featured apps" or "Integration"
- Search for "OpenRegister" or "Open Register"
- Click "Download and enable"

Verify Installation:

# Via command line
php occ app:list | grep openregister

# Should show:
# openregister: 0.2.x enabled

Access the App:
- Navigate to https://your-nextcloud.com/index.php/apps/openregister

Method 2: Manual Installation from Release

For custom installations or when the App Store is unavailable.

Download Latest Release:

cd /path/to/nextcloud/apps/
wget https://github.com/ConductionNL/openregister/releases/latest/download/openregister.tar.gz
tar -xzf openregister.tar.gz
chown -R www-data:www-data openregister

Enable the App:

cd /path/to/nextcloud
sudo -u www-data php occ app:enable openregister

Verify Installation:

sudo -u www-data php occ app:list | grep openregister

Method 3: Development Installation (Docker Compose)

For development, testing, or evaluation purposes.

Quick Start

# Clone the repository
git clone https://github.com/ConductionNL/openregister.git
cd openregister

# Start with PostgreSQL (recommended)
docker-compose up -d

# Access Nextcloud
# URL: http://localhost:8080
# Username: admin
# Password: admin

Detailed Setup

1. Clone and Navigate:

git clone https://github.com/ConductionNL/openregister.git
cd openregister

2. Choose Database Backend:

PostgreSQL (Recommended):

docker-compose up -d

MariaDB (For Compatibility Testing):

docker-compose --profile mariadb up -d

3. Wait for Initialization:

# Check container status
docker-compose ps

# Watch Nextcloud logs
docker-compose logs -f nextcloud

# Wait for: "Nextcloud was successfully installed"

4. Access Nextcloud:

URL: http://localhost:8080
Username: admin
Password: admin

5. Enable OpenRegister:

docker exec -u 33 nextcloud php occ app:enable openregister

6. Verify Installation:

docker exec -u 33 nextcloud php occ app:list | grep openregister

Docker Compose Services

The Docker setup includes:

Service	Description	Port	Optional
nextcloud	Nextcloud application server	8080	Required
db	PostgreSQL database (pgvector)	5432	Required (default)
db-mariadb	MariaDB database	3306	Optional (profile: mariadb)
ollama	Local LLM inference (Llama, Mistral)	11434	Required
presidio-analyzer	PII detection and NER	5001	Required
solr	Search engine (legacy)	8983	Optional (profile: solr)
elasticsearch	Alternative search backend	9200	Optional (profile: elasticsearch)
n8n	Workflow automation	5678	Optional (profile: n8n)

Optional Services

Enable Solr:

docker-compose --profile solr up -d

Enable n8n Workflows:

docker-compose --profile n8n up -d
# Access: http://localhost:5678
# Credentials: admin / admin

Enable All Optional Services:

docker-compose --profile solr --profile n8n --profile elasticsearch up -d

Database Setup

PostgreSQL (Recommended)

PostgreSQL offers advanced features like vector search (pgvector) and full-text search (pg_trgm).

Automatic Setup (Docker)

Extensions are automatically installed via docker/postgres/init-extensions.sql:

✅ pgvector - Vector similarity search
✅ pg_trgm - Trigram full-text search
✅ btree_gin - Optimized GIN indexing
✅ btree_gist - Optimized GiST indexing
✅ uuid-ossp - UUID generation

Manual Setup (Production)

# Connect to PostgreSQL as superuser
psql -U postgres

# Create database
CREATE DATABASE nextcloud;
CREATE USER nextcloud WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE nextcloud TO nextcloud;

# Connect to the database
\c nextcloud

# Install extensions
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS btree_gin;
CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

Verify Extensions

# Check installed extensions
psql -U nextcloud -d nextcloud -c "SELECT extname, extversion FROM pg_extension;"

# Expected output:
#   extname   | extversion
# ------------+------------
#  vector     | 0.8.1
#  pg_trgm    | 1.6
#  btree_gin  | 1.3
#  btree_gist | 1.7
#  uuid-ossp  | 1.1

Nextcloud Configuration

Add to config/config.php:

'dbtype' => 'pgsql',
'dbname' => 'nextcloud',
'dbhost' => 'localhost',
'dbport' => '5432',
'dbuser' => 'nextcloud',
'dbpassword' => 'your_secure_password',
'dbtableprefix' => 'oc_',

MariaDB / MySQL

MariaDB/MySQL are fully supported but lack advanced search features.

Manual Setup

# Connect to MariaDB/MySQL
mysql -u root -p

# Create database
CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'nextcloud'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON nextcloud.* TO 'nextcloud'@'localhost';
FLUSH PRIVILEGES;

Nextcloud Configuration

Add to config/config.php:

'dbtype' => 'mysql',
'dbname' => 'nextcloud',
'dbhost' => 'localhost',
'dbport' => '3306',
'dbuser' => 'nextcloud',
'dbpassword' => 'your_secure_password',
'dbtableprefix' => 'oc_',

Post-Installation Configuration

1. Basic Settings

Access Settings → OpenRegister → Settings:

Organization Name: Your organization name
Default Register: Default register for new objects
API Base URL: Your Nextcloud URL

2. Create First Register

Navigate to OpenRegister → Registers
Click "New Register"
Fill in details:
- Title: E.g., "Contacts"
- Description: Purpose of the register
- Slug: URL-friendly identifier (e.g., "contacts")
Click "Save"

3. Import or Create Schema

Option A: Import from Schema.org

Go to Schemas → Import
Select "Schema.org"
Search and select a schema (e.g., "Person")
Click "Import"

Option B: Create Custom Schema

Go to Schemas → New Schema
Define properties in JSON Schema format
Save the schema

4. Test the Installation

# Via command line
docker exec -u 33 nextcloud php occ openregister:test

# Via API
curl -u admin:admin \
  http://localhost:8080/index.php/apps/openregister/api/registers

# Expected: JSON list of registers

AI Features Setup (Optional)

Ollama Integration

OpenRegister can use Ollama for:

Semantic search
Content understanding
AI-powered chat
RAG (Retrieval Augmented Generation)

1. Pull a Model:

# Inside Docker
docker exec openregister-ollama ollama pull llama3.2

# Alternative models
docker exec openregister-ollama ollama pull mistral
docker exec openregister-ollama ollama pull codellama

2. Verify Ollama:

curl http://localhost:11434/api/tags

3. Configure in OpenRegister:

Navigate to Settings → OpenRegister → AI
Enable "AI Features"
Set Ollama URL: http://ollama:11434
Select model: llama3.2

Presidio PII Detection

For automatic PII detection and anonymization:

Verify Presidio:

curl http://localhost:5001/health

Configure in OpenRegister:

Navigate to Settings → OpenRegister → Privacy
Enable "PII Detection"
Set Presidio URL: http://presidio-analyzer:5001

Troubleshooting

Common Issues

App Not Showing After Installation

# Clear cache
php occ maintenance:mode --on
php occ app:disable openregister
php occ app:enable openregister
php occ maintenance:mode --off

Database Connection Errors

PostgreSQL:

# Check if PostgreSQL is running
docker-compose ps db

# Check logs
docker logs openregister-postgres

# Test connection
docker exec openregister-postgres psql -U nextcloud -d nextcloud -c "SELECT version();"

MariaDB:

# Check if MariaDB is running
docker-compose --profile mariadb ps db-mariadb

# Check logs
docker logs openregister-mariadb

# Test connection
docker exec openregister-mariadb mysql -u nextcloud -p'!ChangeMe!' -e "SELECT VERSION();"

Extensions Not Loaded

# Check PostgreSQL extensions
docker exec openregister-postgres psql -U nextcloud -d nextcloud \
  -c "SELECT extname FROM pg_extension WHERE extname IN ('vector', 'pg_trgm');"

# If missing, recreate database
docker-compose down -v
docker-compose up -d

Port Already in Use

# Find process using port 8080
sudo lsof -i :8080

# Stop the process or change port in docker-compose.yml:
# ports:
#   - "8081:80"  # Change 8080 to 8081

Getting Help

Documentation: https://openregisters.app/
GitHub Issues: https://github.com/ConductionNL/openregister/issues
Community Forum: https://github.com/ConductionNL/openregister/discussions
Email Support: support@conduction.nl

Next Steps

After installation:

Read the User Guide: User Documentation
Explore Features: Feature Documentation
Set Up Access Control: Access Control Guide
Configure Multi-Tenancy: Multi-Tenancy Guide
API Documentation: API Reference

Upgrading

From Nextcloud App Store

Updates are automatic via the Nextcloud update mechanism:

Navigate to Settings → Apps
Look for OpenRegister updates
Click "Update"

From GitHub Release

# Backup first!
php occ maintenance:mode --on
cp -r apps/openregister apps/openregister.backup

# Download and extract new version
cd apps/
wget https://github.com/ConductionNL/openregister/releases/latest/download/openregister.tar.gz
rm -rf openregister
tar -xzf openregister.tar.gz
chown -R www-data:www-data openregister

# Run migrations
php occ upgrade
php occ maintenance:mode --off

Docker Development

# Pull latest changes
git pull origin main

# Rebuild containers
docker-compose down
docker-compose up -d --build

# Run migrations
docker exec -u 33 nextcloud php occ upgrade

Uninstallation

Via App Store

Navigate to Settings → Apps
Find OpenRegister
Click "Remove"

Via Command Line

# Disable and remove
php occ app:disable openregister
php occ app:remove openregister

# Optionally remove data (CAUTION: Cannot be undone!)
# This removes all registers, schemas, objects, and audit trails
php occ openregister:cleanup --force

Docker Development

# Stop and remove all containers and volumes
docker-compose down -v

# Remove cloned repository
cd ..
rm -rf openregister

Production Deployment Checklist

Before deploying to production:

Performance Optimization

Database Tuning

PostgreSQL:

-- Add to postgresql.conf
shared_buffers = 4GB
effective_cache_size = 12GB
maintenance_work_mem = 1GB
work_mem = 32MB
max_connections = 200

MariaDB:

# Add to my.cnf
innodb_buffer_pool_size = 4G
innodb_log_file_size = 512M
max_connections = 200
query_cache_size = 64M

PHP Tuning

Add to php.ini:

memory_limit = 4G
upload_max_filesize = 2G
post_max_size = 2G
max_execution_time = 300
opcache.enable = 1
opcache.memory_consumption = 256

Nextcloud Tuning

Add to config/config.php:

'memcache.local' => '\OC\Memcache\APCu',
'memcache.distributed' => '\OC\Memcache\Redis',
'redis' => [
  'host' => 'localhost',
  'port' => 6379,
],

Support and Resources

Website: https://openregisters.app/
Documentation: https://openregisters.app/docs/
GitHub: https://github.com/ConductionNL/openregister
License: EUPL-1.2
Support: support@conduction.nl

Prerequisites​

System Requirements​

Required PHP Extensions​

Installation Methods​

Method 1: Nextcloud App Store (Recommended for Production)​

Method 2: Manual Installation from Release​

Method 3: Development Installation (Docker Compose)​

Quick Start​

Detailed Setup​

Docker Compose Services​

Optional Services​

Database Setup​

PostgreSQL (Recommended)​

Automatic Setup (Docker)​

Manual Setup (Production)​

Verify Extensions​

Nextcloud Configuration​

MariaDB / MySQL​

Manual Setup​

Nextcloud Configuration​

Post-Installation Configuration​

1. Basic Settings​

2. Create First Register​

3. Import or Create Schema​

4. Test the Installation​

AI Features Setup (Optional)​

Ollama Integration​

Presidio PII Detection​

Troubleshooting​

Common Issues​

App Not Showing After Installation​

Database Connection Errors​

Extensions Not Loaded​

Port Already in Use​

Getting Help​

Next Steps​

Upgrading​

From Nextcloud App Store​

From GitHub Release​

Docker Development​

Uninstallation​

Via App Store​

Via Command Line​

Docker Development​

Production Deployment Checklist​

Performance Optimization​

Database Tuning​

PHP Tuning​

Nextcloud Tuning​

Support and Resources​

Prerequisites

System Requirements

Required PHP Extensions

Installation Methods

Method 1: Nextcloud App Store (Recommended for Production)

Method 2: Manual Installation from Release

Method 3: Development Installation (Docker Compose)

Quick Start

Detailed Setup

Docker Compose Services

Optional Services

Database Setup

PostgreSQL (Recommended)

Automatic Setup (Docker)

Manual Setup (Production)

Verify Extensions

Nextcloud Configuration

MariaDB / MySQL

Manual Setup

Nextcloud Configuration

Post-Installation Configuration

1. Basic Settings

2. Create First Register

3. Import or Create Schema

4. Test the Installation

AI Features Setup (Optional)

Ollama Integration

Presidio PII Detection

Troubleshooting

Common Issues

App Not Showing After Installation

Database Connection Errors

Extensions Not Loaded

Port Already in Use

Getting Help

Next Steps

Upgrading

From Nextcloud App Store

From GitHub Release

Docker Development

Uninstallation

Via App Store

Via Command Line

Docker Development

Production Deployment Checklist

Performance Optimization

Database Tuning

PHP Tuning

Nextcloud Tuning

Support and Resources