KD NAS Project

Overview

KD NAS Project is a comprehensive Network Attached Storage (NAS) solution designed to turn your machine (Mac or Windows) into a powerful home server. It integrates multiple services into a unified dashboard for easy management of photos, files, documents, and system health.

Flowchart

This flowchart illustrates how the components of the NAS interact:

graph TD
    User[User] -->|Access via Browser| Dashboard["Dashboard (Frontend)"]
    User -->|Access Photos| Immich["Immich (Photos)"]
    User -->|Access Files| FileBrowser["File Browser"]
    User -->|Manage Docs| Paperless[Paperless-ngx]
    User -->|Manage Containers| Portainer[Portainer]

    subgraph "Frontend Interface (Port 5178)"
        Dashboard
    end

    subgraph "Backend Services"
        Dashboard -->|Fetch Stats API| Backend["Node.js Backend (Port 3001)"]
        Backend -->|Get System Info| System["System Resources (CPU/RAM)"]
        Backend -->|Get Storage Info| Storage["Disk Usage (/Volumes/KD)"]
        Backend -->|Manage Links| SmartLinks["Smart Links (JSON DB)"]
    end

    subgraph "Docker Containers"
        Immich -->|Store Data| Postgres["Postgres DB"]
        Immich -->|Cache| Redis[Redis]
        Paperless -->|Store Data| Redis
        FileBrowser -->|Read/Write| FileSys["File System"]
    end
    
    subgraph "Remote Access"
        Cloudflare[Cloudflared] -->|Tunnel| Backend
        Cloudflare -->|Tunnel| Immich
        Cloudflare -->|Tunnel| Paperless
    end

Loading

Features

• Centralized Dashboard: View real-time system stats (CPU, RAM, Network), storage usage, and quick links to all services.
• Smart Links: Build-in URL shortener and sharing system to create temporary public links.
• Immich: Self-hosted photo and video management (Google Photos alternative).
• File Browser: Web-based file manager to access your files from anywhere.
• Paperless-ngx: Document management system to go paperless.
• Portainer: UI for managing Docker containers.
• Cross-Platform: Runs on both macOS and Windows.

---

Installation Guide

Prerequisites

1. Docker Desktop: Must be installed and running. Download Here
2. Node.js: Required for the backend and dashboard. Download Here

🍎 For macOS Users

1. Open Terminal in the project directory.
2. Run the Install Script:

   chmod +x INSTALL_MAC.sh
   ./INSTALL_MAC.sh

   This will install dependencies and set up the environment.
3. Start the NAS:

   chmod +x start_nas.sh
   ./start_nas.sh

🪟 For Windows Users

1. Open Command Prompt or PowerShell in the project directory.
2. Run the Install Script: Double-click INSTALL_WINDOWS.bat or run:

   INSTALL_WINDOWS.bat

3. Start the NAS: Double-click start_nas.bat.

---

File Descriptions

File/Folder	Description
backend/	Contains the Node.js server code (server.js) that powers the API for system stats and file operations.
frontend/	Contains the React/Vite dashboard source code.
docker-compose.yml	Defines all Docker services (Immich, Redis, Filebrowser, etc.).
start_nas.sh	(Mac) Main startup script. Launches Docker, Backend, and Frontend.
start_nas.bat	(Windows) Main startup script. Launches Docker, Backend, and Frontend.
INSTALL_MAC.sh	(Mac) Installs node_modules for both backend and frontend.
INSTALL_WINDOWS.bat	(Windows) Installs node_modules for both backend and frontend.
cloudflared	Binary for establishing a secure tunnel to the internet (remote access).
.env	Configuration file for environment variables (DB passwords, paths, etc.).

---

Connections & Architecture

1. Frontend-Backend Connection

• The Dashboard (Frontend) running on port 5178 makes HTTP requests to the Backend on port 3001.
• Endpoints:
  • /api/stats: Fetches CPU, Memory, and Network usage.
  • /api/storage: Fetches disk usage stats for the specific volume.
  • /api/links/*: Manages the Smart Link system.

2. Service Connections (Docker)

• Immich: Connects to the database (Postgres) and redis containers defined in docker-compose.yml.
• Paperless: Uses gotenberg and tika for processing documents and redis for message brokering.
• Data Persistence: All services mount local directories (e.g., ./filebrowser_data, ./local_immich_data) to ensure data is saved even if containers are restarted.

3. Remote Access (Cloudflare Tunnel)

• The cloudflared service creates a secure tunnel between your local ports (e.g., 3001, 2283) and a public domain.
• This allows you to access your NAS from anywhere without port forwarding.

---

How to Upload to GitHub

Follow these steps to upload this project to your repository:

1. Initialize Git (if not already done):

   git init

2. Add Remote Origin:

   git remote add origin https://github.com/dkoustubh/KD-NAS-Project.git

3. Add Files:

   git add .

4. Commit Changes:

   git commit -m "Initial commit: Complete NAS Project with Dashboard and Services"

5. Push to GitHub:

   git branch -M main
   git push -u origin main