Quick start
Run SlugBase locally for development or get a minimal production instance running quickly.
What you need
- Node.js 20 or later, with npm.
- For the fastest production setup: Docker (see Docker or Docker Compose).
New to deployment? After this page, follow Docker Compose, Configuration, and First run setup for a complete path.
Steps
Clone the repository
Clone the SlugBase repository and open the project root in a terminal.
Install dependencies
npm install
Create a local `.env`
Copy .env.example (or example.env) to .env in the project root and fill in at least JWT_SECRET and ENCRYPTION_KEY. These are required for the server to start. See Configuration for the full list and how to generate secure values.
Start dev servers
npm run dev
This runs the backend and frontend together. By default you get:
- Backend API:
http://localhost:5000 - Frontend dev server:
http://localhost:3000
Complete initial setup in the browser
With a fresh database, the app shows Initial Setup so you can create the first admin user. Continue with First run setup for field requirements and what happens next.
Build the app
From the repository root:
npm run build
Set required secrets
Before npm run start, define production secrets and URLs. The server validates JWT_SECRET, ENCRYPTION_KEY, and (in production) SESSION_SECRET. See Configuration for the full list and safe values.
Start the self-hosted server
npm run start
The combined API and built frontend are served from the self-hosted app entrypoint (default port 5000).
Open the app and finish setup
Visit your server URL, complete Initial Setup, then sign in. Use First run setup as the checklist.
Use Docker Compose with the published image
You don't need to clone the repository. Follow Docker Compose to get a ready-made docker-compose.yml, the published mdglabs/slugbase:latest image, and a ./data folder for your database. You only need to clone the repo if you want to build the image yourself.
Verify health
The container health check expects HTTP 200 from /api/health inside the container.
Verify
| Goal | Check |
|---|---|
| Dev API up | Open http://localhost:5000/api/health (or your configured host) and confirm a successful response. |
| Dev UI | Load the frontend URL from Vite (default http://localhost:3000) and reach Initial Setup or login. |
| Production | Load your public origin; after setup you should reach the dashboard at /. |
Troubleshooting
Read the error output: every environment requires strong JWT_SECRET and ENCRYPTION_KEY (minimum length and no insecure defaults). In production only, SESSION_SECRET must also be set with sufficient length. See Configuration.
Confirm both processes from npm run dev are running and that the browser is pointed at the Vite dev URL for the UI. Check the backend terminal log for failed requests.
Related
Last updated 1 week ago
Built with Documentation.AI