205 lines
4.3 KiB
Markdown
205 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
git --version
|
|
```
|
|
|
|
### 3. Clone the repository
|
|
|
|
Open PowerShell or Windows Terminal:
|
|
|
|
```powershell
|
|
git clone https://your-gitea.com/youruser/sloth-manager.git
|
|
cd sloth-manager
|
|
```
|
|
|
|
### 4. Configure the backend
|
|
|
|
```powershell
|
|
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
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```bash
|
|
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
|
sudo apt install -y nodejs
|
|
```
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
### 2. Install Git
|
|
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y git
|
|
```
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
git --version
|
|
```
|
|
|
|
### 3. Clone the repository
|
|
|
|
```bash
|
|
git clone https://your-gitea.com/youruser/sloth-manager.git
|
|
cd sloth-manager
|
|
```
|
|
|
|
### 4. Configure the backend
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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` |
|