MyCloud - Self-Hosted Cloud Storage Solution

A comprehensive, self-hosted cloud storage platform with admin-managed user system, file upload/download capabilities, folder management, and a modern user interface.

Main dashboard view

Features

Admin-Managed Users - Streamlined user management without email verification requirements
File Management - Complete file lifecycle management including upload, download, and deletion
Folder Organization - Hierarchical folder structure for efficient file organization
File Sharing - Share files securely via public links
Storage Quotas - Configurable storage limits per user
Modern Interface - Built with React and Tailwind CSS for a responsive, intuitive experience
Mobile Apps - Native Android and iOS apps via Capacitor
PWA Support - Progressive Web App for installable web experience
Docker Support - Containerized deployment for easy setup and maintenance
JWT Authentication - Secure token-based authentication system

Quick Start for Local Network Use
Quick Start for Online Use with Docker and HTTPS
Manual Installation (without Docker)
Mobile App Setup (Android/iOS)
Usage Guide
Configuration
Production Deployment
Project Structure
Security Features
Database
Troubleshooting
Technology Stack
API Endpoints
Using External Storage
Support
Contributing

Quick Start for Local Network use

For home networks with direct access without HTTPS or reverse proxy complexity.

See here for Production/Online use Configuration

Prerequisites

Docker and Docker Compose installed
Network-connected device (Raspberry Pi, server, or desktop)
Minimum 1GB available storage space

Installation

Navigate to the project directory

cd mycloud

Create a local network configuration

cp .env.local.example .env
nano .env

⚠️ IMPORTANT: You MUST edit .env before proceeding!

Required changes:

JWT_SECRET - Set a strong, random secret key (minimum 32 characters)
ADMIN_PASSWORD - Set a secure administrator password

Generate a secure JWT_SECRET:

openssl rand -base64 32

Build and launch

sudo docker compose -f docker-compose.local.yml up -d --build

Note: The docker-compose.local.yml configuration uses BASE_PATH=/ which is correct for local/direct access. If you're deploying behind a reverse proxy to a subdirectory (e.g., /cloud), use the standard docker-compose.yml which sets BASE_PATH=/cloud.

Find your device's IP address

# On Linux/Mac
hostname -I | awk '{print $1}'

# Or
ip addr show | grep "inet " | grep -v 127.0.0.1

Access MyCloud from any device on your network

Open a browser and navigate to:

http://[YOUR-IP]:6868 (e.g., http://192.168.1.100:6868)
OR http://[HOSTNAME].local:6868 (e.g., http://pi5.local:6868)

Default credentials:

Username: admin
Password: admin123 (or the value you set in .env)

Optional: Set a Static IP Address

For consistent access, configure a static IP on your device:

On Raspberry Pi/Ubuntu:

# Edit netplan configuration
sudo nano /etc/netplan/01-netcfg.yaml

Example configuration:

network:
  version: 2
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.1.100/24
      gateway4: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]

Apply changes:

sudo netplan apply

Management Commands

# View logs
docker compose -f docker-compose.local.yml logs -f

# Restart
docker compose -f docker-compose.local.yml restart

# Stop
docker compose -f docker-compose.local.yml down

# Update and rebuild
docker compose -f docker-compose.local.yml down
docker compose -f docker-compose.local.yml up -d --build

Accessing from Mobile Devices

Ensure your mobile device is on the same WiFi network
Open browser and navigate to http://[YOUR-IP]:6868
Add to home screen for quick access (works like a native app)

Network Considerations

Firewall: Ensure port 6868 is open if using a firewall
Router DNS: Consider adding a DNS entry in your router for easier access
Security: This setup uses HTTP (not HTTPS). Only use within trusted local networks
Port Forwarding: Do NOT expose port 6868 to the internet without proper security measures

Quick Start for online use with Docker and Https

For the public or online use, or in production

Prerequisites

Docker and Docker Compose installed
Letsencrypt or other certificate service installed
Apache2 or Nginx installed
Minimum 1GB available storage space

Installation

Navigate to the project directory

cd mycloud

Configure environment variables

cp .env.example .env

⚠️ IMPORTANT: You MUST edit .env before proceeding!

Required changes:

JWT_SECRET - Set a strong, random secret key (minimum 32 characters)
ADMIN_PASSWORD - Set a secure administrator password

Example of generating a secure JWT_SECRET:

openssl rand -base64 32

# Or use any random string generator

Configure Web Server / Reverse Proxy

Apache Web Server is tested, Nginx should work too.
Generate Certificates with Letsencrypt
See the detailed Web Server Configuration section below for complete setup instructions.

Build the frontend

cd client
npm install
npm run build
cd ..

Launch with Docker Compose

sudo docker compose up -d

Note: The standard docker-compose.yml uses BASE_PATH=/cloud for subdirectory deployment behind a reverse proxy. If you're deploying to the root of a domain (e.g., https://mycloud.example.com), edit docker-compose.yml and change BASE_PATH: /cloud to BASE_PATH: / in both the build.args and environment sections.

Access MyCloud Open your browser and navigate to: https://yourdomain.com/cloud

Default credentials:

Username: admin
Password: admin123 (or the value set in .env)

Manual Installation (without Docker)

Prerequisites

Node.js 18 or higher
npm or yarn

Backend Setup

Install dependencies

npm install

Configure environment

cp .env.example .env

⚠️ IMPORTANT: Edit .env and change at minimum:

JWT_SECRET - Strong secret key (minimum 32 characters)
ADMIN_PASSWORD - Secure password (NOT "admin123")

Start the server

npm start

The server will be available at http://localhost:6868

Frontend Development

Navigate to client directory

cd client

Install dependencies

npm install

Start development server

npm run dev

The frontend will be available at http://localhost:6869 with hot-reload enabled

Production Build

⚠️ IMPORTANT: Configure BASE_PATH before building

The BASE_PATH determines where the application expects to be served from:

Use BASE_PATH=/ for local/direct access (e.g., http://localhost:6868 or http://192.168.1.50:6868)
Use BASE_PATH=/cloud (or other path) for subdirectory deployment behind a reverse proxy (e.g., https://yourdomain.com/cloud)

For Local/Direct Access:

# Build frontend for local access
cd client
npm run build

# Start server in production mode
cd ..
NODE_ENV=production npm start

For Subdirectory Deployment (e.g., behind Apache/Nginx):

# Build frontend with custom base path
cd client
BASE_PATH=/cloud npm run build

# Start server in production mode
cd ..
NODE_ENV=production npm start

Access the application at http://localhost:6868 (or your server's IP/hostname).

Features

✅ Native iOS and Android apps
✅ Installable from app stores or as APK/IPA
✅ Camera and file picker integration
✅ Splash screen and app icons
✅ Offline detection
✅ Configurable server URL
✅ Full feature parity with web version

Quick Start

Install dependencies:
```
cd client
npm install
```
Build the web app:
```
npm run build
```
Initialize Capacitor:
```
cd ..
npx cap init
```

Add platforms:

# For Android
npx cap add android
npm run sync
npm run android  # Opens Android Studio

# For iOS (macOS only)
npx cap add ios
npm run sync
npm run ios  # Opens Xcode

Configuration

Server configuration happens entirely within the app:

On first launch, mobile apps automatically prompt for your server URL
Tap the settings icon (⚙️) on the login screen to change server URL anytime
Configuration is stored locally - no code changes or rebuilding required

Detailed Instructions

For complete setup instructions, requirements, troubleshooting, and build configurations, see:

📱 MOBILE_SETUP.md - Comprehensive mobile app setup guide 🎨 ICON_GUIDE.md - App icon creation and customization guide

Usage Guide

Administrator Functions

Login with admin credentials
Access Admin Panel via the settings icon in the header
Create Users:
- Click "Create User"
- Enter username, email, and password
- Set storage quota (in GB)
- Click "Create User"
Manage Users:
- View all users and their storage utilization
- Delete users as needed

User Functions

Login with credentials provided by administrator
Upload Files:
- Drag and drop files into the upload zone
- Or click to select files manually
Create Folders:
- Click "New Folder"
- Enter folder name
Manage Files:
- Download: Click the download icon
- Share: Click the share icon (link copied to clipboard)
- Delete: Click the trash icon
Navigate:
- Click folders to open them
- Click the back arrow to navigate to parent folder

Configuration

Environment Variables (.env)

# Server Configuration
PORT=6868                    # Server port
NODE_ENV=production          # Environment: production or development

# Security
JWT_SECRET=your-secret-key   # CRITICAL: Change this in production!

# Database
DB_PATH=./data/database.sqlite

# File Storage
UPLOAD_PATH=./data/uploads
MAX_FILE_SIZE=524288000      # 500MB in bytes

# Default Admin User
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123      # CRITICAL: Change this in production!
ADMIN_EMAIL=admin@mycloud.local

Storage Quotas

Default quota per user: 10 GB

This can be customized when creating users in the Admin Panel.

Production Deployment

Docker Deployment (Recommended)

Transfer files to server

scp -r mycloud user@your-server.com:/home/user/

Connect to server

ssh user@your-server.com
cd mycloud

Configure environment (CRITICAL - DO NOT SKIP!)

nano .env

⚠️ PRODUCTION SECURITY: You MUST change these values:

JWT_SECRET - Use a strong random string (minimum 32 characters)
ADMIN_PASSWORD - Use a secure password

Generate a secure JWT_SECRET:

openssl rand -base64 32

Start Docker containers

docker-compose up -d

Configure Reverse Proxy (Optional)

You can deploy MyCloud either at the root of a domain or in a subdirectory.

Option A: Apache (Subdirectory Deployment - Tested & Verified)

This configuration serves MyCloud at https://yourdomain.com/cloud

Enable required Apache modules:

sudo a2enmod proxy proxy_http rewrite headers ssl
sudo systemctl restart apache2

Add to your Apache VirtualHost configuration:

<VirtualHost *:443>
    ServerName yourdomain.com

    # SSL Configuration
    SLEngine on
    SSLCertificateFile /etc/letsencrypt/live/yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

    # MyCloud Proxy Configuration
    ProxyPreserveHost On
    ProxyRequests Off

    # Allow large file uploads (500MB)
    LimitRequestBody 524288000

    # Rewrite Engine for MyCloud
    RewriteEngine On

    # Forward all /cloud/* requests to backend
    RewriteCond %{REQUEST_URI} ^/cloud
    RewriteRule ^/cloud/?(.*) http://localhost:6868/$1 [P,L]

    ProxyPassReverse /cloud http://localhost:6868/

    <Location /cloud>
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Real-IP %{REMOTE_ADDR}s
        RequestHeader set X-Forwarded-For %{REMOTE_ADDR}s
    </Location>
</VirtualHost>

Restart Apache:

sudo systemctl restart apache2

Access your MyCloud at: https://yourdomain.com/cloud

Option B: Nginx (Root Domain Deployment)

This configuration serves MyCloud at https://cloud.yourdomain.com

Create /etc/nginx/sites-available/mycloud:

server {
    listen 80;
    server_name cloud.yourdomain.com;

    client_max_body_size 500M;

    location / {
        proxy_pass http://localhost:6868;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable site and configure SSL with Let's Encrypt:

sudo ln -s /etc/nginx/sites-available/mycloud /etc/nginx/sites-enabled/
sudo certbot --nginx -d cloud.yourdomain.com
sudo systemctl reload nginx

Access your MyCloud at: https://cloud.yourdomain.com

Option C: Nginx (Subdirectory Deployment)

This configuration serves MyCloud at https://yourdomain.com/cloud

server {
    listen 80;
    server_name yourdomain.com;

    client_max_body_size 500M;

    location /cloud {
        rewrite ^/cloud/(.*) /$1 break;
        proxy_pass http://localhost:6868;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Container Management

# View logs
docker-compose logs -f

# Restart containers
docker-compose restart

# Stop containers
docker-compose down

# Update containers
docker-compose pull
docker-compose up -d --build

Project Structure

mycloud/
├── server/               # Backend (Node.js/Express)
│   ├── index.js         # Main server file
│   ├── database/        # Database initialization
│   ├── middleware/      # Authentication middleware
│   └── routes/          # API routes
├── client/              # Frontend (React)
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── pages/       # Application pages
│   │   ├── store/       # State management
│   │   └── api/         # API client
│   └── package.json
├── data/                # Runtime data (created on first run)
│   ├── database.sqlite  # SQLite database
│   └── uploads/         # User uploaded files
├── docker-compose.yml   # Docker configuration
├── Dockerfile
└── README.md

Security Features

JWT-based authentication
Password hashing with bcrypt
CORS protection
Helmet.js security headers
Rate limiting
Input validation
IMPORTANT: Change JWT_SECRET and ADMIN_PASSWORD before production deployment!

Database

The application uses SQLite for simplified deployment. The database is automatically initialized on first startup.

Tables:

users - User account information
files - File metadata
folders - Folder structure
shared_files - File sharing information

Troubleshooting

"Cannot connect to server"

Verify server is running: docker-compose ps
Check logs: docker-compose logs
Ensure port 6868 is available

"Upload failed - Storage quota exceeded"

Administrator can increase quota in Admin Panel
User can delete old files to free up space

"Database locked"

SQLite supports only one concurrent write operation
Consider migrating to PostgreSQL/MySQL for high-traffic deployments

Technology Stack

Backend:

Node.js
Express.js
SQLite
JWT for authentication
bcrypt for password hashing

Frontend:

React
Tailwind CSS
Zustand for state management
Vite for build tooling

API Endpoints

Authentication

POST /api/auth/login - User login
POST /api/auth/register - Create new user (admin only)

Files

GET /api/files - List files
POST /api/files/upload - Upload file
GET /api/files/download/:id - Download file
DELETE /api/files/:id - Delete file
POST /api/files/share/:id - Create share link

Folders

GET /api/folders - List folders
POST /api/folders - Create folder
DELETE /api/folders/:id - Delete folder

Users (Admin only)

GET /api/users - List all users
POST /api/users - Create user
DELETE /api/users/:id - Delete user

Using External Storage

By default, MyCloud stores data in a Docker volume. To use an external disk or different location:

Method 1: Bind Mount (Recommended)

Edit your docker-compose.yml or docker-compose.local.yml:

services:
  mycloud:
    # ... other settings ...
    volumes:
      - /mnt/external-disk/mycloud-data:/app/data

Linux/Raspberry Pi example:

volumes:
  - /mnt/usb-drive/mycloud:/app/data

Windows example:

volumes:
  - D:/MyCloud/data:/app/data

Method 2: Named Volume with Custom Location

volumes:
  mycloud-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/external-disk/mycloud-data

Migration Steps

If you already have existing data and want to move it: ⚠️ Careful, this example uses the compose file for local network usage, use docker-compose.yml otherwise!

# 1. Stop the container
sudo docker compose -f docker-compose.local.yml down

# 2. Create directory on external disk
sudo mkdir -p /mnt/external-disk/mycloud-data

# 3. Copy existing data from Docker volume
sudo docker run --rm \
  -v mycloud-data:/from \
  -v /mnt/external-disk/mycloud-data:/to \
  alpine cp -a /from/. /to/

# 4. Set proper permissions
sudo chown -R 1000:1000 /mnt/external-disk/mycloud-data

# 5. Update docker-compose file with new path
# Change volumes section to use bind mount:
#   volumes:
#     - /mnt/external-disk/mycloud-data:/app/data
# And REMOVE the volumes: definition at the bottom (mycloud-data:)

# 6. Remove old Docker volume completely
# ⚠️This will delete your data if not copied before!⚠️
sudo docker volume rm mycloud_mycloud-data
# If it fails, use: sudo docker compose -f docker-compose.local.yml down -v

# 7. Verify volume is removed
sudo docker volume ls | grep mycloud

# 8. Start container with new location
sudo docker compose -f docker-compose.local.yml up -d

# 9. Verify it's using the correct location
docker inspect mycloud | grep -A 5 Mounts
ls -la /mnt/external-disk/mycloud-data/

MyCloud Mobile App Setup

This guide explains how to build and run MyCloud as a native Android/iOS mobile app using Capacitor.

Prerequisites

For Android Development:

Node.js 16+ and npm
Android Studio (latest version)
Java Development Kit (JDK) 11 or later
Android SDK (installed via Android Studio)

For iOS Development (macOS only):

Node.js 16+ and npm
Xcode 14+ (from Mac App Store)
CocoaPods (sudo gem install cocoapods)
iOS SDK (installed via Xcode)

Initial Setup

1. Install Dependencies

# Navigate to the client directory
cd client

# Install all dependencies including Capacitor packages
npm install

2. Build the Web App

# From the root directory
npm run build

This creates an optimized production build in client/dist with PWA support.

Note: Set "http" in capacitor.config.ts to "https" if used in production/online mode.

Android Setup

1. Add Android Platform

# From the root project directory
npx cap add android

This creates an android/ directory with a native Android project.

2. Sync Web Assets to Android

# Copy web build to native project
npm run sync

# Or use Capacitor CLI directly:
npx cap sync android

3. Open Android Studio

npm run android
# This opens Android Studio with the project

Or manually:

npx cap open android

4. Run on Device/Emulator

In Android Studio:

Wait for Gradle sync to complete
Connect an Android device via USB (with USB debugging enabled) or start an emulator
Click the "Run" button (green play icon) or press Shift+F10
Select your device from the list

The app will install and launch on your device.

iOS Setup (macOS only)

1. Add iOS Platform

# From the root project directory
npx cap add ios

This creates an ios/ directory with a native iOS Xcode project.

2. Sync Web Assets to iOS

npm run sync

# Or use Capacitor CLI directly:
npx cap sync ios

3. Install CocoaPods Dependencies

cd ios/App
pod install
cd ../..

4. Open Xcode

npm run ios
# This opens Xcode with the project

Or manually:

npx cap open ios

5. Run on Device/Simulator

In Xcode:

Select your development team in the "Signing & Capabilities" tab
Select a target device or simulator
Click the "Run" button (play icon) or press Cmd+R

The app will install and launch on your device/simulator.

Making Changes

After modifying the web app code:

Rebuild the web app:
```
cd client
npm run build
```
Sync changes to native projects:
```
npm run sync
```
Rerun the app in Android Studio or Xcode

Support

For issues or questions:

Check logs: docker-compose logs -f
Verify all environment variables are properly set
Ensure port 6868 is not already in use
Review the troubleshooting section above

Contributing

Contributions are welcome.

MyCloud - Your data, your control

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
assets		assets
client		client
server		server
.env.example		.env.example
.env.local.example		.env.local.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
capacitor.config.ts		capacitor.config.ts
docker-compose.local.yml		docker-compose.local.yml
docker-compose.yml		docker-compose.yml
package.json		package.json
restart.local.sh		restart.local.sh
restart.sh		restart.sh

Folders and files

Latest commit

History

Repository files navigation

MyCloud - Self-Hosted Cloud Storage Solution

Features

Table of Contents

Quick Start for Local Network use

Prerequisites

Installation

Optional: Set a Static IP Address

Management Commands

Accessing from Mobile Devices

Network Considerations

Quick Start for online use with Docker and Https

Prerequisites

Installation

Manual Installation (without Docker)

Prerequisites

Backend Setup

Frontend Development

Production Build

Features

Quick Start

Configuration

Detailed Instructions

Usage Guide

Administrator Functions

User Functions

Configuration

Environment Variables (.env)

Storage Quotas

Production Deployment

Docker Deployment (Recommended)

Option A: Apache (Subdirectory Deployment - Tested & Verified)

Option B: Nginx (Root Domain Deployment)

Option C: Nginx (Subdirectory Deployment)

Container Management

Project Structure

Security Features

Database

Troubleshooting

"Cannot connect to server"

"Upload failed - Storage quota exceeded"

"Database locked"

Technology Stack

API Endpoints

Authentication

Files

Folders

Users (Admin only)

Using External Storage

Method 1: Bind Mount (Recommended)

Method 2: Named Volume with Custom Location

Migration Steps

MyCloud Mobile App Setup

Prerequisites

For Android Development:

For iOS Development (macOS only):

Initial Setup

1. Install Dependencies

2. Build the Web App

Android Setup

1. Add Android Platform

2. Sync Web Assets to Android

3. Open Android Studio

4. Run on Device/Emulator

iOS Setup (macOS only)

1. Add iOS Platform

2. Sync Web Assets to iOS

3. Install CocoaPods Dependencies

4. Open Xcode

5. Run on Device/Simulator

Making Changes

Support

Contributing

About

Resources

Stars

Watchers