Buckett is an open-source, self-hosted file manager for project-based uploads. It gives teams a clean admin interface to upload, organize, preview, rename, export, and manage files inside projects and folders.
Click any screenshot to view the full-size image.
Important security note: Buckett is intentionally lightweight and currently uses a simple username and password system. It is not designed as a hardened security platform for sensitive, confidential, or highly regulated documents.
- Project-based file management
- Folder and file organization
- Drag-and-drop uploads
- Upload into existing folders
- Rename projects, folders, and files
- Copy public file URLs with one click
- Preview supported files and images
- CSV export
- Activity logging
- Project-scoped API keys for external gallery apps
- Multiple users
- Light mode, dark mode, and system mode
- Custom accent colors
- Docker-ready deployment
- Username: admin
- Password: admin123
Change these values in your environment before using Buckett in production.
- Install dependencies
- Start the API server
- Start the frontend
Use these commands:
- npm install
- npm run server
- npm run dev
Or run both together:
- npm run dev:all
The app will be available in the browser and the API runs on port 3001.
Buckett supports both a normal Docker Compose installation and a Dockge installation.
Use this when you cloned or downloaded the repository onto your own server or computer.
- Open a terminal in the project root
- Copy the example environment file
- Start the container
- Open Buckett in your browser
Commands:
- cp .env.example .env
- docker compose up -d --remove-orphans
If your system uses the older Compose command, this also works:
- docker-compose up -d --remove-orphans
This uses docker-compose.yml.
Then open:
Use this when you want to deploy through Dockge on a remote server.
Use docker-compose.dockge.yml. This version pulls the latest published Buckett image from GitHub Container Registry, which makes updates much more reliable in Dockge.
Recommended steps:
- Create a new stack in Dockge
- Paste the contents of docker-compose.dockge.yml
- Set your own values for PUBLIC_BASE_URL, ADMIN_USERNAME, and ADMIN_PASSWORD
- Optionally set BUCKETT_TAG to a fixed release such as v1.0.0 for fully predictable updates
- Deploy the stack
Most reliable update flow in Dockge:
- Wait until the GitHub Actions image build has finished after push or release
- In Dockge, change BUCKETT_TAG from the old version to the new version, for example from v0.1.7 to v1.0.0
- Save and Redeploy the stack
Using a fixed version tag is more reliable than only using latest, because some Docker and Dockge setups can keep using a cached latest image until the container is recreated.
If the package is not yet visible on your server, wait until the GitHub Actions build has completed after push.
If you see an error about not being able to connect to the Docker daemon, Docker Desktop or Docker Engine is not running yet.
If you see a Dockerfile not found error, make sure you either:
- run the normal setup from the project root folder
- or use the Dockge stack that builds from GitHub
Docker Compose mounts the following folders so your files and settings stay available after restarts:
- uploads
- data
Available settings:
- PUBLIC_BASE_URL
- ADMIN_USERNAME
- ADMIN_PASSWORD
- API_CORS_ALLOWED_ORIGINS
- API_RATE_LIMIT_PER_MINUTE
See .env.example for the defaults.
Buckett can expose a project-scoped image API for external applications such as a Gallery frontend. API keys are always tied to one project and can optionally be restricted to one folder. By default, a key can read all image files in the linked project. A key cannot request files from other projects.
- Log in to the Buckett admin.
- Open Settings.
- Go to API Keys.
- Enter a clear name, for example
Gallery website. - Choose the project this key may access.
- Leave the folder set to
All foldersfor full project access, or choose one folder to restrict the key. - Create the key and copy it immediately.
The full key is shown only once. Buckett stores only a hash of the key.
Send the key as a Bearer token:
curl -H "Authorization: Bearer API_KEY_HIER" https://buckett-domein.nl/api/v1/gallery/filesMissing or invalid keys return 401 Unauthorized. Requests for files outside the linked project, or outside the optional linked folder, return 403 Forbidden.
GET /api/v1/gallery/files
Returns image metadata for the key's linked project. If the key is folder-restricted, only that folder is returned. Supported query parameters:
- page
- limit
- search
- sort
- direction
- type=image
Example response:
{
"data": [
{
"id": "file-id",
"filename": "voorbeeld.jpg",
"title": "voorbeeld",
"mime_type": "image/jpeg",
"size": 245000,
"width": 1200,
"height": 800,
"url": "https://buckett-domein.nl/api/v1/gallery/files/file-id/download",
"thumbnail_url": "https://buckett-domein.nl/api/v1/gallery/files/file-id/thumbnail",
"created_at": "2026-07-09T10:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 250
}
}GET /api/v1/gallery/files/{id}
Returns metadata for one image if it belongs to the key's linked project and optional folder scope.
GET /api/v1/gallery/files/{id}/download
Returns the original image file if it belongs to the key's linked project and optional folder scope.
GET /api/v1/gallery/files/{id}/thumbnail
Currently returns the original image with an X-Buckett-Thumbnail-TODO response header. Thumbnail generation can be added later without changing the API contract.
Set API_CORS_ALLOWED_ORIGINS to a comma-separated list of Gallery origins:
API_CORS_ALLOWED_ORIGINS=https://gallery-domein.nlLeave it empty for same-origin or server-to-server usage. Browser-based Gallery apps on another domain must be listed explicitly. Set API_RATE_LIMIT_PER_MINUTE to adjust the built-in per-key in-memory rate limit. The default is 120.
Project history and future release notes are tracked here:
This repository is prepared for GitHub and excludes personal uploaded files, backups, runtime data, build output, and local environment files.
MIT