Skip to main content

First-time Setup

This page is the one time setup you do after cloning. After you have done it once, daily development is a single command.

The whole flow takes about ten minutes the first time, mostly because Docker has to download base images and the on prem AI models.

Step 1, Clone the repository​

Pick a folder where your projects live, then:

git clone https://github.com/inaumanmajeed/dashify.git
cd dashify

The repository layout you will see is roughly this:

dashify/
  client/         # the browser app (React + Vite + TypeScript)
  server/         # the API server and worker (Node + Express + TypeScript)
  docs-site/      # this documentation site (Docusaurus)
  scripts/        # one off setup and deploy scripts
  ops/            # infra and observability config
  docker-compose.yml
  pnpm-workspace.yaml
  package.json

You will spend most of your time in client/, server/, and docs-site/.

Step 2, Install dependencies​

From the repo root:

pnpm install

pnpm reads pnpm-workspace.yaml and installs dependencies for the client, the server, and the docs site in one pass. Expect it to take a couple of minutes the first time.

Step 3, Bring up the supporting services​

Dashify depends on MongoDB, Redis, Qdrant (vector database for AI), and Ollama (the local LLM). It would be tedious to install and configure each one yourself, so a single helper script does it for you.

From the repo root:

pnpm up

This script:

  1. Starts the database, cache, vector DB, and LLM in Docker containers.
  2. Waits for each one to become healthy.
  3. Pulls the AI models (nomic-embed-text for embeddings and qwen2.5:1.5b for chat). This is the slow part, about 1 GB of downloads on first run.
  4. Patches server/.env so the API knows how to reach Qdrant and Ollama.

When it finishes, you will see a green status report listing every running service and its port.

Step 4, Configure environment variables​

Inside server/, copy the example environment file:

cp server/.env.example server/.env

Open server/.env and fill in the secrets it lists. The most important ones:

VariableWhat it is
JWT_SECRETA long random string used to sign session tokens. Generate with openssl rand -hex 32.
COOKIE_SECRETSame idea, used to sign cookies. Different value from JWT_SECRET.
CSRF_SECRETUsed by the CSRF protection layer. Different value again.
EMAIL_FROMThe "from" address for outbound emails. The local dev stack uses Mailhog so any address works.
CLOUDINARY_*Optional. Required only if you want to test file uploads.

Everything else in the example file is already set to sensible local dev defaults.

Step 5, Start the application​

pnpm dev

pnpm dev runs the API server, the worker, and the client all together via docker compose up --build. The first run takes a couple of minutes because Docker is building images. Subsequent runs are much faster.

When it finishes you will have:

Step 6, Seed the first admin user​

The first time you start the platform there are no users. The seed script creates a super-admin you can log in as.

From the repo root:

pnpm --filter @dashify/server run seed

This creates a SuperAdmin account whose credentials are printed to the terminal. Write them down. You can change them after first login.

Step 7, Log in​

Open http://localhost:3000 and sign in with the seeded credentials. You should see the SuperAdmin dashboard.

You are now running the full Dashify platform locally.

What just happened (the diagram)​

If something fails​

  • Docker says "port already in use". Another service on your machine is using one of Dashify's ports (3000, 6001, 27017, 6379, 6333, or 11434). Stop that service or change the port in docker-compose.yml.
  • pnpm install fails on argon2 or sharp. These are native modules. On macOS you may need Xcode command-line tools (xcode-select --install). On Windows the official Node installer asks if you want to install build tools, say yes.
  • The AI containers refuse to start (Ollama or Qdrant). They are the heaviest pieces. If your machine is short on RAM, comment them out in docker-compose.yml for now. The platform runs fine without them; only the AI assistant page becomes unavailable.

Key takeaways​

  • Clone, pnpm install, pnpm up, fill in server/.env, pnpm dev, seed.
  • After first time setup, daily development is just pnpm dev.
  • Eight services run in Docker; only Node is on your host machine.
Last updated on