Installation Options

Install using Docker Compose

The quickest way to run a local FAIRSCAPE instance is with Docker Compose. This starts all required services — the API server, web interface, database, object storage, and job queue — in a single command.

# Pull the latest server code and compose yaml from git
git clone http://github.com/fairscape/mds_python
cd mds_python
# Start the FAIRSCAPE services
docker compose up --build

Services Started by Docker Compose

The compose file (compose.yaml) starts the following services:

Service	Description	Local Port
fairscape-api	FAIRSCAPE REST API server	8080
fairscape-frontend	Web UI (React)	5173
mongo	MongoDB metadata store	27017 (internal)
mongo-express	MongoDB admin web UI	8081
minio	S3-compatible object storage	9000 (API), 9001 (console)
redis	Job queue for async uploads	6379 (internal)
fairscape-worker	Background job processor	— (no external port)

Once running, the key interfaces are:

• FAIRSCAPE API: http://localhost:8080/api — REST API; health check at /api/healthz
• FAIRSCAPE API Docs: http://localhost:8080/api/docs — Interactive Swagger UI
• Web Interface: http://localhost:5173 — Browser-based GUI
• MinIO Console: http://localhost:9001 — Object storage admin UI
• Mongo Express: http://localhost:8081 — Database admin UI (login: meadmin / meadmin)

Default Test Credentials

The compose setup uses these default test credentials (defined in deploy/docker_compose.env and compose.yaml):

Service	Username	Password
Web UI / API	test@fairscape.org	password
MongoDB	mongotestaccess	mongotestsecret
MinIO	miniotestadmin	miniotestsecret

Test credentials only

Do not use these defaults in any internet-accessible deployment. Update all credentials in deploy/docker_compose.env before deploying to a shared or production environment.

Optional API Keys (Docker Compose Warnings)

When starting, Docker Compose may print warnings such as:

WARN: The "GEMINI_API_KEY" variable is not set. Defaulting to a blank string.
WARN: The "GITHUB_TOKEN" variable is not set. Defaulting to a blank string.

These warnings are informational — the server starts and functions normally without them. They indicate optional integrations that are not configured:

• GEMINI_API_KEY — Required for LLM-assisted metadata features (server-side AI enrichment and the fairscape-cli track command).
• GITHUB_TOKEN — Required for the D4D (Data Datasheet for Datasets) GitHub integration (/api/github/* endpoints). Without it those endpoints return HTTP 503.

To enable these features, add the keys to deploy/docker_compose.env and restart. See the Configuration page for full details.