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.
- 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
- 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
- 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
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"
}
]
}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.
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
npm install
npm startLAN URL example:
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=trueThen restart service:
sudo systemctl restart localdropUse 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.
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 localdropTarget 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 mainThe 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-webhookGitHub 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-relayWhy 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 -fNotes:
- 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.
- Open login page from iPhone Safari on same Wi-Fi.
- Login with user credentials.
- Create folder, upload files, rename, delete.
- Confirm storage stats update in dashboard.
- Confirm isolation by logging with another user account.
- Login as admin and create users, change roles, remove users, and set quota in GB from the Admin User Management panel.
- Confirm health endpoint:
curl http://127.0.0.1:3000/api/health- 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.