BuildPiper
Non-Root Installation
SOP v1.0

BuildPiper Non-Root User Installation #

Standard Operating Procedure (SOP) — Document Version: v1.0
Target OS: Ubuntu 18 / 20 / 22, RHEL 9
Owner: BuildPiper DevOps / Platform Engineering
Classification: Internal — Contains environment configuration guidance

On This Page

▸Document Control
▸Purpose & How to Use
▸Values You Must Replace
▸1.0 Objective
▸2.0 Prerequisites
▸3.0 Installation Steps
▸3.3 Configuration Setup
▸3.4 Starting Containers

Installation Phases #

System Preparation

Create the buildpiper non‑root user, set up directories, and clone the deployment repository.

Registry & Permissions

Configuration

Update api.json, .env, docker-compose.yml and frontend runtime config.

Database & Launch

Start containers with docker-compose up -d, load environment metadata, and restart APIs.

Document Control #

Document Version

v1.0

Target OS

Ubuntu 18 / 20 / 22, RHEL 9

Owner

BuildPiper DevOps / Platform Engineering

Classification

Internal — Contains environment configuration guidance

Purpose #

This SOP documents the end‑to‑end procedure for installing BuildPiper so that every BP service runs as a dedicated non‑root operating‑system user (buildpiper).

How to Use This Document #

Sections 1‑3 are mandatory for every new installation.

Values You Must Replace #

Every bracketed placeholder (e.g. [GITHUB_TOKEN], [PASSWORD_REQUIRED], <VM_IP>) must be substituted with a real, environment‑specific value sourced from the client credential sheet or secrets vault. No placeholder value should ever be applied to a client or production system as‑is.

Security Note: Default credentials referenced in this SOP (BP admin login, container registry password) are for first‑boot access only. Rotate them immediately after installation, per your organization’s credential security policy.

1.0 Objective #

To establish a standard, secure procedure for setting up BuildPiper (BP) for a non‑root user (buildpiper), ensuring proper directory permissions, Docker socket access, and container operation.

2.0 Prerequisites #

2.1 Hardware & OS Requirements #

Compliant OS

Ubuntu 18.04/20.04/22.04, RHEL 9

Hard Disk

Minimum 100 GB (200 GB recommended for air‑gapped environments.)

Note: The specified disk space is in addition to the space required by the operating system (OS) and should be available exclusively for the application/platform requirements.

RAM

Minimum 16 GB

CPU Cores

Minimum 8 Cores

Ulimit

File descriptor limits set to 65535 (ulimit -n 65535)

2.2 Software Packages (Base VM) #

Docker

Version 24.x or later

Docker Compose

Version v2.20+ (Compose V2 plugin)

Git

Version 2.40+

AWS CLI

v2 (latest release)

HTTPie

Version 3.3.0

2.3 Whitelisting & Ports #

BP Container Repository: https://registry.buildpiper.in

Port(s)	Purpose
80, 443	BP Frontend (HTTP/HTTPS)
9123, 9124, 9125	Worker Agent Ports
9000‑9010	BP Internal Communications & Health Agent Ports
85	MI (Maturity Insights) HTTPS Port
11434	Ollama Endpoint (MCP Server)

2.4 Production Tags #

Obtain the stable production tags for components from the BP product team. Tags shown below are examples validated at time of writing. Always confirm the current production‑stable tags with the BP product team before starting the installation.

Component	Example Tag
Frontend	`spiti‑2.0.2‑major‑GA`
Public API	`spiti‑2.0.2‑major‑GA`
Deploy API	`spiti‑2.0.2‑major‑GA`
BP Agent	`spiti‑2.0.2‑major‑GA`
DB & Redis	`spiti‑2.0.2‑major‑GA`
MI Backend / Frontend	`spiti‑2.0.2‑major‑GA`

3.0 Installation Steps #

3.1 System Preparation & User Creation #

1. Log in to the VM and verify it meets the hardware, OS, and port requirements (Ports 80, 443, 9123, 9124, 9125, 9000‑9005).

2. Clone the deployment repository into /tmp:

cd /tmp

git clone --single‑branch --branch master https://[GITHUB_TOKEN]@github.com/buildipiper/deploy_buildipiper.git

3. Execute the user onboarding script to create the buildpiper user and necessary directory structures:

bash bp_user_and_dir.sh all

4. Switch to the newly created buildpiper user and move the repository:

sudo su buildpiper

cp -r /tmp/deploy_buildpiper /home/buildpiper/

1. Login to the BP Container Registry:

export REGISTRY_USER=admin

export REGISTRY_PASSWORD=[PASSWORD_REQUIRED]

export REGISTRY_URL=https://registry.buildpiper.in

docker login -u ${REGISTRY_USER} -p ${REGISTRY_PASSWORD} ${REGISTRY_URL}

2. Update permissions for the .docker configuration and Docker socket directory:

chown -R buildpiper:buildpiper /home/buildpiper/.docker

chmod 770 /home/buildpiper/.docker/config.json

chmod 770 -R /etc/docker

chown buildpiper:docker /etc/docker

3. Update permissions for Redis and MySQL directories:

chown -R buildpiper:buildpiper /home/buildpiper/.redis

chown -R buildpiper:buildpiper /home/buildpiper/.mysql

3.3 Configuration Setup (api.json, .env, docker-compose.yml) #

1. Identify Group IDs: Find the numerical Group IDs for the buildpiper user and the docker group:

getent group docker

getent group buildpiper

2. Configure api.json: Edit /home/buildpiper/deploy_buildpiper/properties/api.json.

Update "group_id": ["[BUILDPIPER_GID]", "[DOCKER_GID]"] with the numbers obtained above.
Generate and update the secret_key and fernet_key.
Update database password to a strong custom password (match with mysql_env_variable file).
The database username and password must be encrypted using the fernet_key and the encrypted credentials must be updated in the api.json file.
Set runtime_platform and deployment.type to “PAAS” for client setups.

3. Sync Configuration:

cp /home/buildpiper/deploy_buildpiper/properties/api.json /home/buildpiper/conf.d/buildpiper/api.json

cksum /home/buildpiper/deploy_buildpiper/properties/api.json

cksum /home/buildpiper/conf.d/buildpiper/api.json

4. Update mysql_env_variable: Modify the database password to match api.json (default placeholder: ot‑buildpiper).

5. Configure .env: Edit /home/buildpiper/deploy_buildpiper/.env and update HOSTNAME, group_id, and docker_group_id.

6. Configure docker-compose.yml: Update the user and group_add block to ensure the container can access the Docker socket.

7. Update Frontend Config: Edit /home/buildpiper/deploy_buildpiper/public/runtime‑env.js and Update the PUBLIC_API URL with the IP address or DNS name of the VM, for example: http://:9001/Additionally, configure the following organization details: Client Organization Name , Client logo , BuildPiper (BP) tags. The organization details configured during this step must be synchronized with the corresponding organization details defined in api.json to ensure consistency between the frontend and backend configuration.

3.4 Starting Docker Containers & Initializing Database #

1. Start the containers:

docker‑compose up -d

2. Validate Public API Logs – Review the publicapi container logs to identify any exceptions, errors, or failures during startup or operation.

docker logs -f publicapi

Verify that the logs do not contain any exceptions, startup failures, connection errors, or other critical errors.

3. Login to the BP UI using the default first‑boot credentials, then rotate the password immediately per your organization’s credential security policy.

Installation Workflow Summary #

Navigation Path
End‑to‑end installation steps

System Prep
→
User Creation
→
Registry Login
→
Config Setup
→
Containers Up
→Login & Rotate

Final Step: After restarting the API services, log in to the BP UI with the default credentials and rotate the password immediately.

Note: All bracketed placeholders (e.g. [GITHUB_TOKEN], [PASSWORD_REQUIRED], <VM_IP>) must be substituted with real, environment‑specific values sourced from the client credential sheet or secrets vault. No placeholder value should ever be applied to a client or production system as‑is.

BuildPiper Documentation · Non‑Root User Installation SOP

Version v1.0 · Target OS: Ubuntu 18/20/22, RHEL 9

BP Non-Root User Installation