4.3 KiB
Development Environment Setup
This guide walks through installing everything needed to run Sloth Manager locally for development and testing, on both Windows 11 and Debian Linux.
Windows 11
1. Install Node.js
Download and run the LTS installer from https://nodejs.org (choose "LTS").
Verify the installation:
node --version
npm --version
Both commands should return a version number.
2. Install Git
Download and run the installer from https://git-scm.com/download/win.
Accept the defaults. When asked about the default editor, choose whichever you prefer.
Verify:
git --version
3. Clone the repository
Open PowerShell or Windows Terminal:
git clone https://your-gitea.com/youruser/sloth-manager.git
cd sloth-manager
4. Configure the backend
cd backend
copy .env.example .env
notepad .env
Fill in your provider credentials. At minimum set a JWT_SECRET:
JWT_SECRET=any-long-random-string-for-dev
5. Install dependencies and start the backend
npm install
npm run dev
The backend will start on http://localhost:3001. Leave this terminal open.
6. Configure and start the frontend
Open a second terminal window:
cd frontend
copy .env.example .env
npm install
npm start
The browser will open automatically at http://localhost:3000.
7. First login
Log in with admin / admin and change the password immediately in 👤 My Profile.
Debian (12 Bookworm / 11 Bullseye)
1. Install Node.js
The version in Debian's default repositories is outdated. Install the current LTS via NodeSource:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
Verify:
node --version
npm --version
2. Install Git
sudo apt update
sudo apt install -y git
Verify:
git --version
3. Clone the repository
git clone https://your-gitea.com/youruser/sloth-manager.git
cd sloth-manager
4. Configure the backend
cd backend
cp .env.example .env
nano .env
Fill in your provider credentials. At minimum set a JWT_SECRET:
JWT_SECRET=any-long-random-string-for-dev
5. Install dependencies and start the backend
npm install
npm run dev
The backend will start on http://localhost:3001. Leave this terminal open.
6. Configure and start the frontend
Open a second terminal:
cd frontend
cp .env.example .env
npm install
npm start
Open http://localhost:3000 in your browser.
7. First login
Log in with admin / admin and change the password immediately in 👤 My Profile.
Verify everything is working
Once both services are running, confirm the following in the browser:
- The login page loads at
http://localhost:3000 - After logging in, the Overview page shows the dashboard
- Selecting a provider and pressing ⟳ Sync fetches records without errors
- ⚙️ Settings → Provider Status → Run Check shows green for configured providers
Stopping the development servers
Press Ctrl+C in each terminal to stop the backend and frontend.
Useful development tips
Backend auto-restarts — nodemon watches for file changes and restarts the backend automatically. You do not need to restart it manually after editing backend files.
Frontend hot-reloads — the React dev server reloads the browser automatically when frontend files change.
Nodemon and new files — if you add a brand new file to the backend (not just edit an existing one), nodemon may not pick it up. Stop it with Ctrl+C and run npm run dev again.
Viewing backend logs — all errors and audit events are printed to the terminal running the backend.
Data files — in development, data files (users.json, dns-cache.json, etc.) are created in the backend/ folder. These are gitignored and will not be committed.
Summary of commands
| Task | Windows | Debian |
|---|---|---|
| Copy env file | copy .env.example .env |
cp .env.example .env |
| Install deps | npm install |
npm install |
| Start backend | npm run dev |
npm run dev |
| Start frontend | npm start |
npm start |
| Open app | http://localhost:3000 |
http://localhost:3000 |