Installation | UReport Docs

Option A — Docker (recommended)

How do I run UReport with Docker Compose?

No local Node.js or MongoDB install required — everything is bundled.

1

Clone and start

bash

git clone https://github.com/ureport-web/ureport-standalone.git
cd ureport-standalone

bash

docker-compose up --build

--build compiles the app image from the included Dockerfile — no pre-built image to pull.

Open http://localhost:8080. Default login: admin / changeme.

2

(Optional) Custom credentials or external DB

Copy .env.example to .env and edit before the first startup:

bash

cp .env.example .env
# edit .env, then:
docker-compose up --build

.env

# Admin credentials (applied on first startup only)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
DEMO_PASSWORD=1234

# External MongoDB (optional)
# DBHost=mongodb+srv://user:pass@cluster.mongodb.net/ureport

Credentials in .env are only applied on the first startup when the database is empty.

Does data persist across restarts?

Yes. MongoDB data is stored in a named Docker volume (mongo_data) and survives container restarts and rebuilds.

Can I use an external MongoDB instead of the bundled one?

Set DBHost in .env to your MongoDB URI. The bundled mongodb service in docker-compose.yml can then be removed to avoid starting an unnecessary container.

Option B — Bare metal

What do I need before installing?

Node.js 18+ — runtime for the server
MongoDB 3+ — database (local, Atlas, or AWS DocumentDB)

How do I get UReport running without Docker?

1

Clone the repository

bash

git clone https://github.com/ureport-web/ureport-standalone.git
cd ureport-standalone
npm install

2

Configure your database

Edit config/dev.json with your MongoDB connection string and desired port:

config/dev.json

{
  "DBHost": "mongodb://localhost:27017/ureport",
  "PORT": 4100
}

For production, edit config/production.json — or set the DBHost environment variable to override the config file.

3

Seed the database

This creates the default admin account and initial system settings. Safe to re-run — skips if already initialized.

bash

npm run initialize

4

Start the server

bash

npm start

The server starts on the port configured in step 2 (default: 4100 for dev).

Running in Production (bare metal)

How do I run UReport in production mode?

Set NODE_ENV=production before starting. This switches the server to use config/production.json and enables clustering (4 workers):

bash

NODE_ENV=production npm start

You can also override the database connection with an environment variable:

bash

DBHost="mongodb+srv://user:pass@cluster.mongodb.net/ureport" \
NODE_ENV=production npm start

First Login

What are the default credentials?

Setup	Username	Password
Docker Compose	`admin`	`changeme`
Docker Compose	`demo`	`1234`
Bare metal	`admin`	`1234`

Docker credentials can be changed via .env before the first startup.

Change the admin password immediately after your first login.

How do other users get access?

Users self-register at /signup. How they get activated depends on whether email is configured:

With email configured (recommended)

User registers → receives a confirmation email → clicks the link → account becomes active automatically. No admin action needed.

Without email configured

User registers → account stays pending → admin must manually approve in Settings → Users before the user can log in.

To configure email go to Settings → Notification → Email and enter your SMTP credentials.

Admins can promote users to operator or admin role in Settings → Users.

API Token

How do I get an API token to push test results?

Each user can generate a personal API token from their profile — click your avatar → Edit Profile → API Token → Generate Token. This token is used in the Authorization: Bearer header when calling the REST API or configuring a reporter plugin.

Configuration Reference

Where does UReport read its configuration?

Configuration is loaded from the config/ directory based on the NODE_ENV value:

File	Used when
`config/dev.json`	`NODE_ENV=dev` (default)
`config/production.json`	`NODE_ENV=production`
`config/docker.json`	`NODE_ENV=docker` (set by docker-compose.yml)
`config/test.json`	`NODE_ENV=test`

Each file supports two keys:

Key	Description	Dev default	Prod default
`DBHost`	MongoDB connection string	mongodb://localhost:27017/ureport	(set this to your DB)
`PORT`	HTTP port the server listens on	4100	8080

Can I override config values with environment variables?

Yes. These environment variables take precedence over the config files:

Variable	Overrides	Notes
`DBHost`	`config.DBHost`	Useful in Docker / cloud deployments
`PORT`	`config.PORT`	Falls back to 3000 if neither is set
`NODE_ENV`	(selects config file)	Defaults to `dev`
`ADMIN_EMAIL`	Admin seed email	Docker only — applied on first startup
`ADMIN_PASSWORD`	Admin seed password	Docker only — applied on first startup
`DEMO_PASSWORD`	Demo user seed password	Docker only — applied on first startup