x/safebin
1
0
Fork 0
mirror of https://github.com/skidoodle/safebin.git synced 2026-04-28 19:27:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update readme

Browse Source 
Signed-off-by: skidoodle <contact@albert.lol>
This commit is contained in:
albert
2026-01-16 02:50:15 +01:00
parent 2af23db0ad
commit 344b3b312a
2 changed files with 38 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+37 -52
View File
@@ -4,74 +4,47 @@
## Features
- **Server-Side Encryption**: Files are encrypted using AES-256-GCM before touching the disk.
- **Log-Safe Keys**: The decryption key is stored in the URL fragment (`#`). Since fragments are never sent to the server, the key never appears in your HTTP access logs.
- **End-to-End Encryption**: Files are encrypted using AES-128-GCM before being written to disk.
- **Key-Derived URLs**: The decryption key is part of the URL. The server uses this key to locate and decrypt the file on the fly.
- **Integrity**: Uses GCM (Galois/Counter Mode) to ensure files cannot be tampered with while stored.
- **Deterministic**: Identical files result in the same ID, allowing for storage deduplication.
- **Storage Deduplication**: Identical files result in the same ID, saving disk space.
- **Chunked Uploads**: Supports large file uploads via the web interface using 8MB chunks.
## Usage
You can interact with the service via the web interface or through the command line.
### Web Interface
Simply drag and drop files into the browser. The interface handles chunking and provides a shareable link once the upload is finalized.
### Uploading a file
### Command Line (CLI)
You can upload files directly using `curl`:
```bash
curl -F 'file=@archive.zip' https://bin.example.com
curl -F 'file=@photo.jpg' https://bin.example.com
```
The server will return a URL containing the file ID and the decryption key:
`https://bin.example.com/vS6_1_8pS-Y_8-8_...`
### Downloading a file
Simply open the link in a browser or use `curl`:
```bash
curl https://bin.example.com/vS6_1_8pS-Y_8-8_... > archive.zip
```
The server will return a direct link:
`https://bin.example.com/0iEZGtW-ikVdu...jpg`
## Configuration
`safebin` is configured via command-line flags:
`safebin` can be configured via environment variables or command-line flags:
| Flag | Description | Default |
| :--- | :--- | :--- |
| `-h` | Bind address for the server. | `0.0.0.0` |
| `-p` | Port to listen on. | `8080` |
| `-s` | Directory where encrypted files are stored. | `./storage` |
| `-m` | Maximum file size in mb. | `512` |
| Flag | Environment Variable | Description | Default |
| :--- | :--- | :--- | :--- |
| `-h` | `SAFEBIN_HOST` | Bind address for the server. | `0.0.0.0` |
| `-p` | `SAFEBIN_PORT` | Port to listen on. | `8080` |
| `-s` | `SAFEBIN_STORAGE` | Directory for encrypted storage. | `./storage` |
| `-m` | `SAFEBIN_MAX_MB` | Maximum file size in MB. | `512` |
## Running Locally
### With Docker
```bash
git clone https://github.com/skidoodle/safebin
cd safebin
docker compose -f compose.dev.yaml up --build
```
### Without Docker
Requires Go 1.25 or higher.
```bash
git clone https://github.com/skidoodle/safebin
cd safebin
go build -o safebin .
./safebin -p 8080 -s ./data
```
## Deploying
## Deployment
### Docker Compose
The easiest way to deploy is using the provided `compose.yaml`.
The easiest way to deploy is using the provided `compose.yaml`:
```yaml
services:
safebin:
image: ghcr.io/skidoodle/safebin:main
image: ghcr.io/skidoodle/safebin:latest
container_name: safebin
restart: unless-stopped
ports:
@@ -88,10 +61,22 @@ volumes:
data:
```
### Manual Build
Requires Go 1.25 or higher.
```bash
go build -o safebin .
./safebin -p 8080 -s ./data
```
## Retention Policy
The server runs a cleanup task every hour. Retention is calculated using a cubic scaling formula to balance disk usage:
- **Small files (< 1MB)**: Up to 365 days.
- **Large files (512MB)**: 24 hours.
The server runs a background cleanup task every hour. Retention is calculated using a cubic scaling formula to prioritize small files:
This ensures that the server doesn't run out of disk space due to large binary blobs while allowing small text files or images to persist for longer periods.
- **Small files (e.g., < 1MB)**: Kept for up to **365 days**.
- **Large files (at Max MB)**: Kept for **24 hours**.
- **Temporary Uploads**: Unfinished chunked uploads are purged after **4 hours**.
## License
This project is licensed under the **GNU General Public License v2.0**.
compose.yaml
+1 -1
View File
@@ -1,6 +1,6 @@
services:
safebin:
image: ghcr.io/skidoodle/safebin:main
image: ghcr.io/skidoodle/safebin:latest
container_name: safebin
restart: unless-stopped
ports: