Deploy S3 Explorer

S3 Explorer

A secure, self-hosted web-based file manager for S3-compatible storage buckets.

Overview

Managing S3 buckets often requires command-line tools or provider-specific dashboards that vary significantly in usability. S3 Explorer unifies this experience by offering a single, consistent web interface to upload, download, and organize files across any S3-compatible provider.

Supported Providers:

1. AWS S3
2. Cloudflare R2
3. MinIO
4. DigitalOcean Spaces
5. Any S3-compatible storage

Screenshots

Architecture

flowchart TB
    subgraph Client["Browser Client"]
        UI["React + Tailwind UI"]
        API["API Client"]
    end

    subgraph Server["Express Server"]
        Auth["Auth Middleware"]
        Routes["API Routes"]
        Session["Session Store"]
        Crypto["AES-256-GCM"]
    end

    subgraph Storage["Persistence Layer"]
        SQLite[("SQLite DB")]
        EncKey["Encryption Key"]
    end

    subgraph External["S3 Providers"]
        S3["AWS S3 / R2 / MinIO"]
    end

    UI --> API
    API -->|HTTPS + Cookies| Auth
    Auth --> Routes
    Routes --> Session
    Routes --> Crypto
    Session --> SQLite
    Crypto --> EncKey
    Crypto --> SQLite
    Routes -->|S3 SDK| S3

Security Features

1. Password Auth: Single password via env var or setup wizard (Argon2id hashed)
2. Encrypted Credentials: S3 credentials encrypted at rest with AES-256-GCM
3. Secure Sessions: Server-side SQLite sessions with httpOnly/secure/sameSite=strict cookies
4. Rate Limiting: IP-based, 10 attempts per 15 min, 30 min lockout
5. Security Headers: Helmet.js enabled (CSP, HSTS, etc.)
6. No Client Storage: Credentials never stored in browser localStorage

Features

File Management

1. Drag-and-drop file uploads
2. Create folders for organization
3. Rename files and folders
4. Delete files and folders with confirmation
5. Batch select and delete multiple items
6. Download files through secure server proxy
7. In-browser file preview

Multi-Connection Support

1. Store up to 100 S3 connections
2. Instant switching between connections
3. All credentials encrypted server-side

Keyboard Navigation

1. Cmd+K / Ctrl+K: Open command palette
2. Cmd+, / Ctrl+,: Open connection manager
3. Cmd+U / Ctrl+U: Upload files
4. Escape: Close active modal

Deployment

Railway (Recommended)

1. Fork repo
2. New project → Deploy from GitHub
3. Add volume: mount path /data
4. Set environment variables:
   1. APP_PASSWORD: Strong password (12+ chars, mixed case, numbers, symbols)
   2. SESSION_SECRET: Random 32+ character string (use openssl rand -hex 32)

Or skip these and configure through the setup wizard on first launch.

Docker

docker run -d \
  -p 3000:3000 \
  -e APP_PASSWORD='YourStr0ng!Pass#2024' \
  -e SESSION_SECRET='your-random-32-char-session-secret' \
  -v s3explorer_data:/data \
  ghcr.io/subratomandal/s3-explorer:latest

Docker Compose

services:
  s3-explorer:
    build: .
    ports:
      - "3000:3000"
    environment:
      - APP_PASSWORD=YourStr0ng!Pass#2024
      - SESSION_SECRET=change-this-to-a-random-32-char-secret
    volumes:
      - s3explorer_data:/data

volumes:
  s3explorer_data:

Local Development

npm run install:all

export APP_PASSWORD='DevPassword123!'
export SESSION_SECRET='dev-session-secret-32-characters!'
export DATA_DIR='./data'

npm run dev

Backend runs on :3000, frontend on :5173.

Environment Variables

1. APP_PASSWORD (optional): Login password. Must be 12+ chars with upper, lower, number, special char. If not set, a setup wizard will appear on first launch to configure it.
2. SESSION_SECRET (optional): Session signing key. Use openssl rand -hex 32. If not set, a setup wizard will appear on first launch to configure it.
3. DATA_DIR (optional): SQLite/key storage path. Default: /data
4. PORT (optional): Server port. Default: 3000
5. NODE_ENV (optional): Environment (production / development)

Provider Setup Guide

Cloudflare R2

1. Go to Cloudflare Dashboard → R2 Object Storage
2. Click Manage R2 API Tokens
3. Create token with Admin Read & Write permissions
4. Use values:
   1. Endpoint: https://.r2.cloudflarestorage.com
   2. Access Key: Your R2 Access Key ID
   3. Secret Key: Your R2 Secret Access Key

AWS S3

1. Go to AWS Console → IAM
2. Create user with AmazonS3FullAccess policy
3. Create access key under Security Credentials
4. Use values:
   1. Endpoint: https://s3..amazonaws.com
   2. Access Key: Generated Access Key ID
   3. Secret Key: Generated Secret Access Key

MinIO

1. Access your MinIO console
2. Navigate to Access Keys
3. Create new access key
4. Use values:
   1. Endpoint: Your MinIO URL (e.g., https://minio.example.com)
   2. Access Key: Generated Access Key
   3. Secret Key: Generated Secret Key

Stack

1. Frontend: React, Tailwind, Vite
2. Backend: Express, TypeScript
3. Database: SQLite (better-sqlite3)
4. Auth: Argon2, express-session

License

MIT

Created by @subratomandal