https://github.com/pluja/pocketjson
A lightweight and simple single-binary JSON storage service
https://github.com/pluja/pocketjson
bin database golang json store
Last synced: 2 months ago
JSON representation
A lightweight and simple single-binary JSON storage service
- Host: GitHub
- URL: https://github.com/pluja/pocketjson
- Owner: pluja
- License: mit
- Created: 2024-12-30T20:34:53.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-21T20:27:03.000Z (8 months ago)
- Last Synced: 2025-10-21T22:22:18.621Z (8 months ago)
- Topics: bin, database, golang, json, store
- Language: Go
- Homepage: https://pocketjson.pluja.dev
- Size: 81.1 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PocketJSON 🚀
A lightweight, single-binary JSON storage service with built-in expiry and multi-tenant support. Perfect for developers who need a quick, reliable way to store and retrieve JSON data without the overhead of a full database setup.
## Features ✨
- **Zero Configuration**: Just run the binary and you're ready to go
- **Built-in Expiry**: All stored JSONs automatically expire (configurable)
- **Multi-tenant Support**: Managed API keys with isolated namespaces
- **Guest Mode**: Quick storage without authentication
- **Size Limits**: 100KB for guests, 1MB for authenticated users
- **Docker Ready**: Easy deployment with Docker and docker-compose
- **SQLite Backend**: Simple, reliable, and portable
- **Automatic Cleanup**: Background process removes expired data
## Quick Start 🚀
### Using Docker
#### Option 1: Docker Pull (Easiest)
```bash
docker pull ghcr.io/pluja/pocketjson:latest
docker run -d -p 9819:9819 -v $(pwd)/data:/app/data ghcr.io/pluja/pocketjson:latest
```
#### Option 2: Docker Compose
1. Copy the `docker-compose.yml` file
2. Run `docker-compose up -d`
3. (optional) Set the `MASTER_API_KEY` env variable to a `.env` file
### Direct Usage
- Download the latest release from the releases page.
- Build it yourself:
```bash
# Build
go build -o pocketjson ./cmd/pocketjson
# Run
./pocketjson
```
### Configuration via Environment Variables 🔧
| Variable | Description | Default | Required |
| ---------------------- | ----------------------------------------- | -------------------------------- | -------- |
| MASTER_API_KEY | Master key for administrative operations | *random value, see std output* | No |
| PORT | HTTP server port | `9819` | No |
| DATA_DIR | Directory for SQLite database | `data` | No |
| REQUEST_LIMIT | Rate limit requests per minute for guests | 15 | No |
| DEFAULT_EXPIRY_HOURS | Default expiry time for stores | `48` | No |
| DEFAULT_MAX_SIZE | Maximum JSON size for guests in bytes | `102400` (100kb) | No |
| AUTHENTICATED_MAX_SIZE | Maximum JSON size for auth users in bytes | `1048576` (1M) | No |
| CORS_ALLOWED_ORIGINS | Allowed origins for CORS | `*` | No |
> If you are using `docker` create a `.env` file next to the `docker-compose.yml` and add the variables you need. If you are running it without docker, please declare the variables you need.
## API Usage 📡
### Guest Mode
Store JSON (expires in 48 hours by default):
```bash
curl -X POST http://localhost:9819 \
-H "Content-Type: application/json" \
-d '{"hello":"world"}'
# Response:
{
"id": "f7a8b9c0d1e2",
"expires_at": "2024-01-21T15:30:45Z"
}
```
Retrieve JSON:
```bash
curl http://localhost:9819/f7a8b9c0d1e2
```
### Authenticated Mode
First, create an API key (requires master key):
```bash
curl -X POST http://localhost:9819/admin/keys \
-H "X-API-Key: your-master-key" \
-H "Content-Type: application/json" \
-d '{
"description": "Development API Key",
"is_admin": false
}'
# Response:
{
"key": "924a98c84222ca4b2984e417c767c519",
"client_id": "7f3d8",
"description": "Development API Key",
"is_admin": false,
"created_at": "2024-01-20T15:30:45Z"
}
```
Store JSON with custom expiry:
```bash
# Expire after 3 days
curl -X POST "http://localhost:9819/my-data?expiry=72" \
-H "X-API-Key: 924a98c84222ca4b2984e417c767c519" \
-H "Content-Type: application/json" \
-d '{"hello":"world"}'
# Response:
{
"id": "7f3d8_my-data",
"expires_at": "2024-01-23T15:30:45Z"
}
```
Note: Authenticated users' IDs are prefixed with their client_id (first 5 chars of MD5(api_key))
## API Reference 📚
### Endpoints
| Method | Path | Description | Auth Required |
|--------|------|-------------|---------------|
| POST | / | Store JSON with random ID | No |
| POST | /{id} | Store JSON with specific ID | Yes |
| GET | /{id} | Retrieve JSON | No |
| POST | /admin/keys | Create API key | Yes (Admin) |
| DELETE | /admin/keys/{key} | Delete API key | Yes (Admin) |
| GET | /health | Health check | No |
### Storage Limits
- Guest users: 100KB
- Authenticated users: 1MB
### Expiry Options
- Guest users: 48 hours
- Authenticated users can specify:
- Custom hours: `?expiry=72` (72 hours)
- Never expire: `?expiry=never`
## Development 🛠
### Prerequisites
- Go 1.23+
- SQLite3
### Setup
```bash
# Build
go build -o pocketjson ./cmd/pocketjson
# Run
./pocketjson
```
## Why PocketJSON? 🤔
PocketJSON was created to solve the common need for temporary JSON storage without the complexity of setting up and maintaining a full database system. It's perfect for:
- Development and testing
- Temporary data storage
- Webhook payload storage
- API response caching
- Cross-service data sharing
## License 📄
MIT License - see [LICENSE](LICENSE) for details
## Contributing 🤝
Contributions are welcome! Please feel free to submit a Pull Request.