ZotPrime2

Self-hosted platform for Zotero

ZotPrime2 is a fully packaged repository aimed to make self-hosted Zotero deployment easier with the last versions of both Zotero client and server. This is the result of sleepless nights spent to deploy Zotero within my organization on a disconnected network.

Feel free to open issues or pull requests if you did not manage to use it.

Supported Architectures

• x86_64 (amd64)
• ARM64 (aarch64)

---

Table of Contents

• Docker Installation
• GKE Installation
• MicroK8s Installation
• Manage Users and Groups
• Client Build
• Credits

---

Docker Installation

1. Identify Your Server IP Address

You may install ZotPrime server in:

• Baremetal - Use the IP address of your network interface connected to LAN
• Virtual Machine - Use either:
  • IP address of your hypervisor's/VMM's virtual network interface connected to host
  • IP address of your host's network interface connected to LAN (requires port forwarding for all endpoints listed below)
• Same PC as Client - Use 127.0.0.1 (localhost)

Note: This IP address will be referred to as <SERVER_IP> throughout this guide.

2. Install Dependencies

Install Prerequisites:

• Docker Engine

Install latest Docker Compose plugin:

sudo apt update
sudo apt install docker-compose-plugin

Install required tools for secret generation:

sudo apt install openssl php-cli

3. Clone Repository

mkdir /path/to/your/app && cd /path/to/your/app
git clone --recursive https://github.com/uniuuu/zotprime.git
cd zotprime

4. Start Server

./bin/install.sh

Configure: When prompted, input the IP address of the server from Identify Your Server IP Address.

The system will automatically initialize databases and services on first startup.

Available Endpoints

Service	URL
Zotero API	http://<SERVER_IP>:8080/
S3	http://<SERVER_IP>:9000/
PHPMyAdmin	http://<SERVER_IP>:8083/
S3 Web UI	http://<SERVER_IP>:9001/
Stream Server	ws://<SERVER_IP>:8081/

Default Credentials

All credentials are configured in the .env file:

• Zotero API: ADMIN_USERNAME / ADMIN_PASSWORD
• S3 Web UI: MINIOROOTUSER / MINIOROOTPASSWORD
• PHPMyAdmin: root / MARIADB_ROOT_PASSWORD

---

GKE Installation

1. Clone Repository

mkdir /path/to/your/app && cd /path/to/your/app
git clone https://github.com/uniuuu/zotprime.git
cd zotprime

2. Install Prerequisites

• Google Cloud SDK
• Terraform
• Kubectl
• Helm

3. Configure GCP Service Account

gcloud init
gcloud iam service-accounts create zotprimeprod
gcloud projects list
gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/owner"

Note:

• <PROJECT_ID> - Your GCP project ID
• NAME@PROJECT_ID.iam.gserviceaccount.com - Service account email

4. Setup Terraform

cd ./zotprime-k8s/GKE/terraform
gcloud iam service-accounts keys create cred.json \
  --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com
mv cred.json ./auth/
gcloud services enable container.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
cp terraform.tfvars_example terraform.tfvars

Edit terraform.tfvars and configure:

• project_id
• region
• zones
• node-locations
• minnode
• maxnode
• disksize
• machine

5. Deploy Infrastructure

terraform init
terraform fmt && terraform validate && terraform plan
terraform apply
gcloud container clusters get-credentials zotprime-k8s-prod
cd ..

6. Install Zotprime Helm Chart

Check cluster status:

kubectl config get-contexts
kubectl get all --all-namespaces

Edit ./helm-chart/values.yaml and update hostnames:

dsuri: http://api-any.yourhostname.io/
s3Pointuri: s3-any.yourhostname.io
api: api-any.yourhostname.io
streamserver: stream-any.yourhostname.io
minios3Data: s3-any.yourhostname.io
phpmyadmin: phpmyadmin-any.yourhostname.io
minios3Web: minioweb-any.yourhostname.io

Deploy:

kubectl create namespace zotprime
helm install zotprime-k8s helm-chart --namespace zotprime
kubectl get -A cm,secrets,deploy,rs,sts,pod,pvc,svc,ing

7. Configure DNS

Wait for GCP to provision IPs:

kubectl get -A ing

Check the ADDRESS column and setup A records in your DNS hosting.

Available Endpoints

Service	URL
Zotero API	http://yoursub1.yourdomain.tld
S3	http://yoursub2.yourdomain.tld
Stream Server	ws://yoursub5.yourdomain.tld
Web Admin	http://yoursub6.yourdomain.tld
Web Portal	http://yoursub7.yourdomain.tld

Admin Services (VPN-only):

• PHPMyAdmin: http://10.7.7.10
• MinIO Web UI: http://10.7.7.11

Default Credentials

Credentials are configured in the .env file:

• Zotero API: ADMIN_USERNAME / ADMIN_PASSWORD
• S3 Web UI: MINIOROOTUSER / MINIOROOTPASSWORD
• PHPMyAdmin: root / MARIADB_ROOT_PASSWORD

---

MicroK8s Installation

1. Clone Repository

mkdir /path/to/your/app && cd /path/to/your/app
git clone https://github.com/uniuuu/zotprime.git

2. Install Prerequisites

• MicroK8s
• Kubectl
• Helm
• Docker Engine - Install Docker CE with BuildKit and Compose plugins from Docker's official repository

3. Enable MicroK8s Modules

Enable required addons:

microk8s enable hostpath-storage
microk8s enable helm
microk8s enable registry
microk8s enable dns
microk8s enable ingress

Enable MetalLB with your LAN IP range (guide):

microk8s enable metallb:<IP_RANGE>

4. Verify Cluster

kubectl config get-contexts
kubectl get all --all-namespaces

5. Build and Push Images

cd zotprime/microk8s/scripts
./buildimages.sh
./pushimages.sh

6. Install Zotprime Helm Chart

cd ../
kubectl create namespace zotprime
helm install zotprime-k8s helm-chart --namespace zotprime
kubectl get -A cm,secrets,deploy,rs,sts,pod,pvc,svc,ing

7. Configure DNS

Get Ingress IPs:

kubectl get -A ing

Setup A records in DNS servers or add entries to /etc/hosts on client and server machines.

Available Endpoints

Service	URL
Zotero API	http://api.zotprime
S3	http://s3min.zotprime
PHPMyAdmin	http://pm.zotprime
S3 Web UI	http://min.zotprime
Stream Server	ws://stream.zotprime

Default Credentials

Service	Login	Password
Zotero API	admin	admin
S3 Web UI	zotero	zoterodocker
PHPMyAdmin	root	zotero

---

Manage Users and Groups

The admin.sh script provides a unified interface for managing users and groups.

User Management

Create User

./bin/admin.sh docker user create <username> <email> <password>

Example:

./bin/admin.sh docker user create alice alice@example.com password123

List Users

./bin/admin.sh docker user list

Output shows userID, username, email, and status (enabled/disabled).

Show User Quota

./bin/admin.sh docker user quota <user_id>

Set User Quota

./bin/admin.sh docker user set-quota <user_id> <quota_mb>

Disable User

./bin/admin.sh docker user disable <username>

Enable User

./bin/admin.sh docker user enable <username>

Group Management

Create Group

./bin/admin.sh docker group create <owner_id> <name> <type>

Group types:

• PublicOpen - Anyone can join, no file attachments
• PublicClosed - Visible to all, requires approval to join
• Private - Invitation-only, not publicly visible

Example:

./bin/admin.sh docker group create 1 "Research Team" Private

List Groups

./bin/admin.sh docker group list

Shows all groups with ID, name, type, owner, and member count.

Delete Group

./bin/admin.sh docker group delete <group_id>

Add User to Group

./bin/admin.sh docker group add-user <group_id> <user_id> [role]

Roles: member (default) or admin

Example:

./bin/admin.sh docker group add-user 1 2 member
./bin/admin.sh docker group add-user 1 3 admin

Remove User from Group

./bin/admin.sh docker group remove-user <group_id> <user_id>

List Group Members

./bin/admin.sh docker group members <group_id>

Kubernetes Mode

For Kubernetes deployments, replace docker with k8s:

./bin/admin.sh k8s user create alice alice@example.com password123
./bin/admin.sh k8s group list

---

Client Build

Linux Build

Build Client

Set MLW argument:

• w = Windows
• l = Linux

For Docker Installation:

DOCKER_BUILDKIT=1 docker build --progress=plain --file client.Dockerfile \
  --build-arg HOST_DS=http://<SERVER_IP>:8080/ \
  --build-arg HOST_ST=ws://<SERVER_IP>:8081/ \
  --build-arg MLW=l --output build .

For GKE Installation:

DOCKER_BUILDKIT=1 docker build --progress=plain --file client.Dockerfile \
  --build-arg HOST_DS=http://api-any.yourhostname.io/ \
  --build-arg HOST_ST=ws://stream-any.yourhostname.io/ \
  --build-arg MLW=l --output build .

For MicroK8s Installation:

DOCKER_BUILDKIT=1 docker build --progress=plain --file client.Dockerfile \
  --build-arg HOST_DS=http://api.zotprime/ \
  --build-arg HOST_ST=ws://stream.zotprime/ \
  --build-arg MLW=l --output build .

Run Client

./build/staging/Zotero_VERSION/zotero

For Windows build:

./build/staging/Zotero_VERSION/zotero.exe

---

Mac Build

1. Install Git LFS

sudo port install git-lfs

2. Build Client

Note: The -p m flag specifies Mac platform.

git submodule update --init --recursive
cd client
./config.sh
cd zotero-client
npm install
npm run build
app/scripts/dir_build -p m

3. Run Client

./staging/Zotero_VERSION/zotero

---

Connect to Zotero

Use credentials from .env file (ADMIN_USERNAME / ADMIN_PASSWORD).

---

Credits

This project builds upon the work of:

• FiligranHQ/zotprime
• gfacciol/zotero_dataserver-docker
• isabekov/dataserver
• piernov/zotprime
• Dwarf-Planet-Project/zotero_installation
• foxsen/zotero-selfhost
• zehuanli/zotero-selfhost
• fversaci/zotero-prime
• victoradrianjimenez/dockerized-zotero