Prerequisites

Describes the local tools required before installing SolidX and explains why they matter.

Required Tooling

Note

These installation instructions are provided as a guideline. Environments differ, so if you run into issues, you can troubleshoot by consulting the relevant official documentation or searching for solutions on the internet.

Mental Model

Think of the SolidX prerequisites as the minimum layers required to make a metadata-driven application development environment work.

Database stores both application data and SolidX metadata.
Git versions your code and metadata changes safely.
Node.js + npm power solidctl, dependency installation, and local builds.
Python 3.12+ is required if you plan to use the SolidX MCP server or SolidX agent, because both runtimes are Python-based.
Supporting CLI tools help with workflow steps such as code generation and asset handling.

The setup order is straightforward: prepare persistence first, then the core toolchain, then the smaller helper utilities the workflow depends on.

1. Database Setup

Why this matters

SolidX is a metadata-driven platform. That means the database is not just storing business records, it is also storing the metadata that defines how much of the platform behaves.

So when we say “set up the database,” what we really mean is:

Prepare the persistence layer for your application data.
Prepare the persistence layer for SolidX metadata.
Ensure the local project has somewhere to seed and run against.

This guide assumes you're using PostgreSQL as your database.

If you're using a different database, please refer to its official documentation.

Installing PostgreSQL

On Ubuntu / macOS

Follow DigitalOcean's guide for detailed installation instructions.

Alternatively, you can use your package manager of choice or follow the official PostgreSQL docs for your OS.

# Example for Ubuntu:
sudo apt update
sudo apt install postgresql postgresql-contrib -y

# Validate installation:
psql --version
systemctl status postgresql --no-pager

Create a PostgreSQL User and Database

Create a user:

sudo -u postgres createuser --interactive

Validate: list users

sudo -u postgres psql -c "\du"

Update the password:

ALTER USER <user> WITH PASSWORD '<password>';

Create and access the database:

sudo -u postgres createdb <dbname>
psql -U <user> -h localhost -d <dbname>

Validate

inside psql, run \dt to check available tables.

2. Git Installation

Why this matters

SolidX projects are normal application codebases. Your metadata, backend code, frontend code, and configuration all live in source control.

That means Git is not optional in practice if you want to:

Collaborate with other developers.
Version metadata changes safely.
Review changes.
Move work across environments cleanly.

On Ubuntu / macOS

Note

If you already have Git installed via another method (Xcode, Homebrew, source build), you can skip this step. You can also search “install git on your distro” for alternatives.

sudo apt update
sudo apt install git -y

# Validate installation:
git --version

# Configure user details:
git config --global user.name "<User Name>"
git config --global user.email "<User Email>"
git config --list   # Validate configuration

3. Node.js & npm Setup (via nvm)

Why this matters

Node.js is the runtime behind the project tooling for SolidX development.

You need it because:

solidctl runs through the Node.js toolchain,
Project dependencies for solid-api and solid-ui are installed through npm.
Local build/dev workflows depend on a working Node environment.

We recommend nvm because different projects may move across Node versions over time, and version management tends to keep development machines healthier.

On Ubuntu / macOS

You may also use your OS package manager (e.g., brew install node) or download binaries from Node.js official site. We recommend nvm for version management.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Validate installation:
nvm --version

# Install Node.js (example: v22)
nvm install 22

# Validate versions:
node -v
npm -v

4. Python 3.12+

Why this matters

Python is required if you plan to install or run the SolidX MCP server or use the SolidX agent, because both runtimes are Python-based.

If you are only working with the core SolidX application (API + UI), Python is not needed. It becomes a requirement the moment you bring in the MCP server or agent tooling.

On Ubuntu / macOS

We recommend using pyenv to manage Python versions, similar to how nvm manages Node.js. This keeps your system Python untouched and lets you switch versions cleanly.

# Install pyenv (Ubuntu / macOS)
curl https://pyenv.run | bash

# Reload shell, then install Python 3.12
pyenv install 3.12
pyenv global 3.12

# Validate installation:
python --version   # should show Python 3.12.x
pip --version

Alternative

On macOS you can also use Homebrew: brew install python@3.12. On Ubuntu, use the deadsnakes PPA if 3.12 is not available in the default apt repos.

5. Install `schematics-cli`

Why this matters

SolidX uses Angular schematics to generate parts of the backend codebase, including controllers and services.

Because this is part of the code-generation workflow rather than the application runtime, schematics-cli is only needed on development machines and not on production servers.

Alternatively, you can install it locally in your project and run via npx. Check Angular schematics docs for details.

npm install -g @angular-devkit/schematics-cli

# Validate installation:
schematics --version

6. Install `copyfiles`

Why this matters

SolidX uses copyfiles during parts of the development and build setup workflow to move static assets into the expected project locations.

Like schematics-cli, this belongs to the development toolchain rather than the application runtime, so it is only needed on development machines and not on production servers.

If you prefer, you can add copyfiles as a project dependency and use it via npx. See copyfiles on npm for options.

npm install -g copyfiles

# Validate installation:
copyfiles --help | head -n 5

Prerequisites

On this page