173 lines
5.4 KiB
Markdown
173 lines
5.4 KiB
Markdown
# Sloth Manager
|
|
|
|
A self-hosted web app to manage DNS records across Cloudflare, Loopia, Pi-hole, Azure DNS, and cPanel from a single interface.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 18+
|
|
- npm
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### 1. Backend
|
|
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your credentials and settings. See `ENVIRONMENT.md` for a full reference of every variable.
|
|
|
|
Start the backend:
|
|
|
|
```bash
|
|
npm run dev # development (auto-restarts on saved file changes)
|
|
npm start # production
|
|
```
|
|
|
|
> **Note:** `npm run dev` uses nodemon and will automatically restart when you edit existing files. However, if you add a **new file** to the project while nodemon is running, you need to stop (`Ctrl+C`) and restart manually — nodemon does not detect brand new files being required for the first time.
|
|
|
|
### 2. Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm start # dev server on http://localhost:3000
|
|
```
|
|
|
|
For production, build the static files and serve them via nginx or similar:
|
|
|
|
```bash
|
|
npm run build # outputs to frontend/build/
|
|
```
|
|
|
|
---
|
|
|
|
## First run
|
|
|
|
On first start the backend automatically creates a default admin account and prints a warning in the terminal:
|
|
|
|
```
|
|
⚠ No users found — created default admin account.
|
|
⚠ Username: admin Password: admin
|
|
⚠ Change this password immediately in Settings → Users.
|
|
```
|
|
|
|
Log in with `admin` / `admin`, then go to **👤 My Profile** to change the password.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
1. Open `http://localhost:3000` and sign in
|
|
2. The **🏠 Overview** page shows statistics based on your locally cached records
|
|
3. The **🌍 All Domains** page shows every zone across all providers in one table — duplicate domains across providers are highlighted
|
|
4. Select a provider from the sidebar, then select a zone to see its domains
|
|
5. Press **⟳ Sync** to fetch the latest records from the provider — this is the only action that calls the provider API for reads
|
|
6. Add, edit, or delete records directly from the table — changes apply to the provider immediately and update the local cache
|
|
7. All record changes are logged in **📋 Audit Log**
|
|
8. Configure notifications, users, provider tag colours, and cache under **⚙️ Settings**
|
|
|
|
---
|
|
|
|
## Data files
|
|
|
|
The backend stores these files at runtime:
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `backend/dns-cache.json` | Local cache of synced DNS records |
|
|
| `backend/settings.json` | App settings (Gotify, provider colours) |
|
|
| `backend/users.json` | User accounts (hashed passwords) |
|
|
| `backend/audit-log.json` | Record change history (last 500 entries) |
|
|
|
|
All files are created automatically on first use.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| File | Contents |
|
|
|------|---------|
|
|
| `ENVIRONMENT.md` | Every `.env` variable explained |
|
|
| `API-ACCESS.md` | API credentials and permissions for each provider |
|
|
| `NOTIFICATIONS.md` | Gotify notification setup and troubleshooting |
|
|
|
|
---
|
|
|
|
## Adding more providers
|
|
|
|
1. Create `backend/src/adapters/yourprovider.js` exporting:
|
|
- `listZones()` → `[{ id, name }]`
|
|
- `listRecords(zoneId)` → `[{ id, type, name, content, ttl, priority }]`
|
|
- `addRecord(zoneId, record)` → `{ id, ... }`
|
|
- `updateRecord(zoneId, recordId, record)` → `{ id, ... }`
|
|
- `deleteRecord(zoneId, recordId)`
|
|
|
|
2. Register it in `backend/src/routes/zones.js` and `records.js`
|
|
|
|
3. Add its env vars to `.env`
|
|
|
|
4. **Restart the backend** after making these changes
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
```
|
|
dns-manager/
|
|
├── backend/
|
|
│ ├── src/
|
|
│ │ ├── index.js # Express server entry point
|
|
│ │ ├── db.js # JSON file cache
|
|
│ │ ├── settings.js # Settings persistence
|
|
│ │ ├── notify.js # Gotify notification helper
|
|
│ │ ├── audit.js # Audit log
|
|
│ │ ├── auth.js # JWT helpers & middleware
|
|
│ │ ├── users.js # User management
|
|
│ │ ├── routes/
|
|
│ │ │ ├── zones.js
|
|
│ │ │ ├── records.js
|
|
│ │ │ ├── settings.js
|
|
│ │ │ ├── auth.js
|
|
│ │ │ └── users.js
|
|
│ │ └── adapters/
|
|
│ │ ├── cloudflare.js
|
|
│ │ ├── loopia.js
|
|
│ │ ├── pihole.js
|
|
│ │ ├── azure.js
|
|
│ │ └── cpanel.js
|
|
│ ├── dns-cache.json # created on first sync
|
|
│ ├── settings.json # created on first save
|
|
│ ├── users.json # created on first start
|
|
│ ├── audit-log.json # created on first change
|
|
│ ├── .env.example
|
|
│ └── package.json
|
|
└── frontend/
|
|
├── src/
|
|
│ ├── App.js
|
|
│ ├── App.css
|
|
│ ├── index.js
|
|
│ ├── api/dns.js
|
|
│ ├── context/
|
|
│ │ ├── ProviderColors.js
|
|
│ │ └── Theme.js
|
|
│ ├── utils/
|
|
│ │ └── exportCsv.js
|
|
│ └── components/
|
|
│ ├── LoginPage.js
|
|
│ ├── Dashboard.js
|
|
│ ├── DomainsPage.js
|
|
│ ├── ProviderOverview.js
|
|
│ ├── RecordsTable.js
|
|
│ ├── AddRecordForm.js
|
|
│ ├── AuditPage.js
|
|
│ ├── ProfilePage.js
|
|
│ ├── SettingsPage.js
|
|
│ └── ConfirmDialog.js
|
|
└── package.json
|
|
```
|