Skip to content
MatsoDevPublic

About

LAN storage platform with SSH-based remote backend, per-device isolation, and resumable uploads.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

HomeCloud Storage Grid

HomeCloud is a LAN-only multi-device storage platform built on Node.js and Express. Each device authenticates with credentials and is isolated to its own storage root on the laptop server.

Core Architecture

  • Auth module: device credentials and session tokens
  • Storage module: isolated remote storage access via SSH/SFTP under /home/{server_user}/storage/{device_id}
  • Filesystem module: folders, upload, rename, delete, preview, download
  • System module: health, LAN URL, QR code

Authentication Model

  • No anonymous storage access
  • Login requires user_id + password
  • Session uses Bearer token
  • Default bootstrap device and bootstrap admin are created automatically on first start
  • Admin sessions can create users, change roles, remove users, and update per-user quota

Storage Isolation Model

  • Device root (remote): /home/mats/storage/{device_id}/
  • Internal upload temp (remote): /home/mats/storage/{device_id}/.incoming/
  • All file operations execute on matsoserver via SSH/SFTP
  • Internal paths are blocked from API access

Device Registry Schema

Path: storage/.auth/devices.json

{
  "version": 1,
  "createdAt": "2026-04-11T20:00:00.000Z",
  "updatedAt": "2026-04-11T20:00:00.000Z",
  "devices": [
    {
      "deviceId": "mats-device",
      "password": { "salt": "...", "hash": "..." },
      "token": null,
      "role": "device",
      "quotaMb": 10240,
      "createdAt": "2026-04-11T20:00:00.000Z",
      "updatedAt": "2026-04-11T20:00:00.000Z"
    }
  ]
}

API Overview

Public:

  • GET /api/health
  • GET /api/network
  • POST /api/auth/login

Authenticated (Bearer token):

  • GET /api/auth/me
  • POST /api/auth/logout
  • GET /api/storage/list?path=
  • GET /api/storage/stats
  • POST /api/storage/folders
  • PATCH /api/storage/rename
  • DELETE /api/storage/item?path=
  • POST /api/storage/upload?path=
  • GET /api/storage/preview?path=
  • GET /api/storage/download?path=

Admin only (Bearer token with role=admin):

  • POST /api/auth/users
  • GET /api/auth/users
  • PATCH /api/auth/users/:userId/quota
  • PATCH /api/auth/users/:userId/role
  • DELETE /api/auth/users/:userId
  • GET /api/auth/devices (legacy alias)
  • PATCH /api/auth/devices/:deviceId/quota (legacy alias)
  • PATCH /api/auth/devices/:deviceId/role (legacy alias)
  • DELETE /api/auth/devices/:deviceId (legacy alias)

Quota request notes:

  • Admin APIs accept quotaGb (preferred) or quotaMb.
  • Responses include both quotaMb and quotaGb.

Environment

Copy .env.example to .env and adjust values:

  • PORT=3000
  • HOST=0.0.0.0
  • HTTPS_ENABLED=false
  • HTTPS_PORT=3443
  • HTTPS_KEY_PATH=/home/mats/certs/homecloud.key
  • HTTPS_CERT_PATH=/home/mats/certs/homecloud.crt
  • HTTPS_REDIRECT_HTTP=true
  • STORAGE_ROOT=/home/mats/storage
  • AUTH_REGISTRY_PATH=./storage/.auth/devices.json
  • SSH_HOST=192.168.1.115
  • SSH_PORT=22
  • SSH_USER=mats
  • SSH_PASSWORD=447700
  • BOOTSTRAP_DEVICE_ID=mats-device
  • BOOTSTRAP_DEVICE_PASSWORD=447700
  • BOOTSTRAP_ADMIN_DEVICE_ID=admin
  • BOOTSTRAP_ADMIN_PASSWORD=447700
  • SYNC_BOOTSTRAP_ADMIN_PASSWORD=true
  • ALLOW_DEVICE_REGISTRATION=false
  • DEVICE_SETUP_KEY=447700
  • AUTH_SESSION_HOURS=24
  • DEVICE_QUOTA_MB=10240
  • MAX_FILE_SIZE_MB=1024
  • MAX_FILES_PER_UPLOAD=20
  • UPLOAD_REQUEST_TIMEOUT_SEC=900
  • LAN_ONLY=true

Run Local

npm install
npm start

LAN URL example:

HTTPS Setup (Fix "Not Secure")

If the browser shows "connection is not secure", enable HTTPS and trust a local certificate.

Generate certificate on Ubuntu server:

mkdir -p /home/mats/certs
openssl req -x509 -nodes -newkey rsa:2048 \
  -keyout /home/mats/certs/homecloud.key \
  -out /home/mats/certs/homecloud.crt \
  -days 825 \
  -subj "/CN=192.168.1.115" \
  -addext "subjectAltName=IP:192.168.1.115"

Enable HTTPS in /home/mats/your-project/.env:

HTTPS_ENABLED=true
HTTPS_PORT=3443
HTTPS_KEY_PATH=/home/mats/certs/homecloud.key
HTTPS_CERT_PATH=/home/mats/certs/homecloud.crt
HTTPS_REDIRECT_HTTP=true

Then restart service:

sudo systemctl restart localdrop

Use this URL:

Important:

  • Browsers will still warn until the certificate is trusted on each device.
  • Install and trust /home/mats/certs/homecloud.crt on phones/laptops to remove warnings fully.

Ubuntu Service (matsoserver)

Expected identity:

  • Hostname: matsoserver
  • User: mats
sudo cp deploy/localdrop.service /etc/systemd/system/localdrop.service
sudo systemctl daemon-reload
sudo systemctl enable --now localdrop
sudo systemctl status localdrop

GitHub Repository

Target repository:

First-time local publish:

git init -b main
git add .
git commit -m "Initial HomeCloud commit"
git remote add origin https://github.com/MatsoDev/HomeCloud.git
git push -u origin main

Auto Deploy From GitHub Push

The repo includes deployment-only files:

  • deploy/deploy.sh
  • deploy/webhook.js
  • deploy/homecloud-webhook.service
  • deploy/homecloud-webhook.env.example

Server setup on Ubuntu (run as mats user, using sudo where shown):

cd /home/mats/localdrop

# Install deploy trigger script and webhook listener
cp deploy/deploy.sh /home/mats/deploy.sh
cp deploy/webhook.js /home/mats/webhook.js
chmod +x /home/mats/deploy.sh

# Optional webhook secret and runtime overrides
cp deploy/homecloud-webhook.env.example /home/mats/.homecloud-webhook.env

# Keep requested path /home/mats/your-project mapped to the running project
ln -sfn /home/mats/localdrop /home/mats/your-project

# Allow non-interactive service restart from deploy script
echo "mats ALL=(root) NOPASSWD: /usr/bin/systemctl restart localdrop" | sudo tee /etc/sudoers.d/homecloud-deploy
sudo chmod 440 /etc/sudoers.d/homecloud-deploy

# Install and start webhook service
sudo cp deploy/homecloud-webhook.service /etc/systemd/system/homecloud-webhook.service
sudo systemctl daemon-reload
sudo systemctl enable --now homecloud-webhook
sudo systemctl status homecloud-webhook

GitHub webhook settings:

  • URL: https://smee.io/
  • Method: POST
  • Content type: application/json
  • Events: Just the push event

Webhook relay fix for private LAN servers (recommended):

# Create relay env with your smee channel
cp deploy/homecloud-webhook-relay.env.example /home/mats/.homecloud-webhook-relay.env

# Example channel (generate from https://smee.io/new)
sed -i 's#https://smee.io/replace-with-your-channel#https://smee.io/2u7IB1byactErh2K#g' /home/mats/.homecloud-webhook-relay.env

# Install and start relay service
sudo cp deploy/homecloud-webhook-relay.service /etc/systemd/system/homecloud-webhook-relay.service
sudo systemctl daemon-reload
sudo systemctl enable --now homecloud-webhook-relay
sudo systemctl status homecloud-webhook-relay

Why this works:

  • GitHub delivers to public smee URL.
  • Relay service forwards webhook payload to local listener at http://127.0.0.1:9000.
  • Deploy flow remains unchanged on server.

Logs:

journalctl -u homecloud-webhook -f
journalctl -u homecloud-webhook-relay -f
journalctl -u localdrop -f

Notes:

  • On push to main, webhook triggers /home/mats/deploy.sh, which pulls latest code and restarts localdrop.
  • If WEBHOOK_SECRET is set in /home/mats/.homecloud-webhook.env, signature validation is enforced.
  • For LAN-only servers, keep webhook URL on smee relay instead of private IP.

Verify

  1. Open login page from iPhone Safari on same Wi-Fi.
  2. Login with user credentials.
  3. Create folder, upload files, rename, delete.
  4. Confirm storage stats update in dashboard.
  5. Confirm isolation by logging with another user account.
  6. Login as admin and create users, change roles, remove users, and set quota in GB from the Admin User Management panel.
  7. Confirm health endpoint:
curl http://127.0.0.1:3000/api/health

Capacity Notes

  • Filesystem stats in dashboard come from the remote laptop server storage root configured by STORAGE_ROOT.
  • If SSH is unavailable, storage operations fail with remote storage errors and do not fall back to local disk.

About

LAN storage platform with SSH-based remote backend, per-device isolation, and resumable uploads.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages