Skip to content

Commit 6005942

Browse files
PdzlyPdzly
committed
docs: update README with enhanced deployment instructions and feature list
- Expand feature list with detailed descriptions - Add comprehensive setup instructions for both development and production - Include environment variable configuration reference and troubleshooting guidelines
1 parent 52a7786 commit 6005942

File tree

1 file changed

+155
-13
lines changed

1 file changed

+155
-13
lines changed

‎README.md‎

Lines changed: 155 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,168 @@
11
# DevBin – The Bin for all your Pasting needs
22

3-
A simple pastebin service written in Python using FastAPI for the Backend and using Svelt for the Frontend.
3+
A lightweight and modern pastebin service built with FastAPI (Python) for the backend and Svelte for the frontend. Share
4+
code snippets, text, and more with ease.
45

56
## Features
67

7-
- Simple and clean interface
8-
- Syntax highlighting
9-
- Paste expiration
10-
- Straightforward to deploy
8+
- **Simple and Clean Interface** – Intuitive UI for quick paste creation and sharing
9+
- **Syntax Highlighting** – Support for multiple programming languages
10+
- **Paste Expiration** – Automatic cleanup of expired pastes
11+
- **Rate Limiting** – Built-in protection with configurable limits and bypass tokens
12+
- **Caching Layer** – LRU cache for improved performance
13+
- **Legacy Paste Support** – Backward compatibility with older paste formats
14+
- **Health Monitoring** – Built-in health check endpoint and storage monitoring
15+
- **Docker Ready** – Easy deployment with Docker Compose
16+
- **Configurable Storage** – Customizable file storage and size limits
17+
- **Trusted Hosts** – IP-based access control
18+
19+
## Tech Stack
20+
21+
- **Backend**: FastAPI, SQLAlchemy, PostgreSQL, Alembic (migrations)
22+
- **Frontend**: Svelte
23+
- **Deployment**: Docker, Docker Compose
24+
- **Caching**: LRU Memory Cache with configurable TTL
1125

1226
## Requirements
1327

1428
- Docker Engine
15-
- Docker Compose
29+
- Docker Compose (or `docker-compose` for older versions)
1630

1731
## Installation
1832

19-
> Note: You maybe required to use docker-compose instead of docker compose depending on your docker version
33+
> **Note**: Depending on your Docker version, you may need to use `docker-compose` instead of `docker compose`
34+
35+
### Quick Start
36+
37+
DevBin can be deployed in two ways:
38+
39+
#### Option 1: Development Setup
40+
41+
1. **Clone the repository**
42+
```bash
43+
git clone <repository-url>
44+
cd DevBin
45+
```
46+
47+
2. **Configure environment variables**
48+
```bash
49+
cp .env.example .env
50+
```
51+
Edit `.env` and update the values according to your needs. Key configurations include:
52+
- Database credentials
53+
- API port and host
54+
- Rate limiting settings
55+
- CORS domains
56+
- Storage paths and limits
57+
- Trusted hosts
58+
59+
3. **Start the services**
60+
```bash
61+
docker compose up -d
62+
```
63+
64+
4. **Run database migrations**
65+
```bash
66+
docker compose run --rm app uv run alembic upgrade head
67+
```
68+
69+
5. **Access the application**
70+
- Frontend: http://localhost:3000
71+
- API Documentation (Swagger): http://localhost:8000/docs
72+
- Health Check: http://localhost:8000/health
73+
74+
#### Option 2: Production Setup
75+
76+
For production deployment, you only need the production compose file and environment configuration:
77+
78+
1. **Clone the repository**
79+
```bash
80+
git clone <repository-url>
81+
cd DevBin
82+
```
83+
84+
2. **Configure environment variables**
85+
```bash
86+
cp .env.example .env
87+
```
88+
Edit `.env` with production-ready values (strong passwords, proper domains, etc.)
89+
90+
3. **Start the services**
91+
```bash
92+
docker compose -f docker-compose.prod.yml up -d
93+
```
94+
95+
4. **Run database migrations**
96+
```bash
97+
docker compose -f docker-compose.prod.yml run --rm app uv run alembic upgrade head
98+
```
99+
100+
### Stopping the Service
101+
102+
Development:
103+
104+
```bash
105+
docker compose down
106+
```
107+
108+
Production:
109+
110+
```bash
111+
docker compose -f docker-compose.prod.yml down
112+
```
113+
114+
## Configuration
115+
116+
Key environment variables in `.env`:
117+
118+
| Variable | Description | Default |
119+
|--------------------------|-----------------------------------------|---------------------------|
120+
| `APP_PORT` | Backend API port | 8000 |
121+
| `APP_MAX_CONTENT_LENGTH` | Maximum paste size | 10000 |
122+
| `APP_WORKERS` | Number of worker processes | 1 |
123+
| `APP_BYPASS_TOKEN` | Token to bypass rate limits | - |
124+
| `APP_CACHE_TTL` | Cache time-to-live (seconds) | 300 |
125+
| `APP_MIN_STORAGE_MB` | Minimum required storage (MB) | 1024 |
126+
| `TRUSTED_HOSTS` | Array of trusted IP addresses/hostnames | ["127.0.0.1"] |
127+
| `APP_CORS_DOMAINS` | Allowed CORS origins | ["http://localhost:3000"] |
128+
129+
See `.env.example` for a complete list of configuration options.
130+
131+
## Development
132+
133+
### Running in Development Mode
134+
135+
Set these variables in `.env`:
136+
137+
```env
138+
APP_DEBUG=true
139+
APP_RELOAD=true
140+
APP_SQLALCHEMY_ECHO=true
141+
```
142+
143+
### API Endpoints
144+
145+
- `GET /health` – Health check
146+
- `GET /pastes/{paste_id}` – Retrieve a paste
147+
- `GET /pastes/legacy/{paste_id}` – Retrieve a legacy paste
148+
- `POST /pastes` – Create a new paste
149+
150+
Full API documentation available at `/docs` when running.
151+
152+
## Production Deployment
153+
154+
See **[Option 2: Production Setup](#option-2-production-setup)** in the Quick Start section above for deployment
155+
instructions.
156+
157+
### Production Checklist
158+
159+
Make sure to configure the following in your `.env` file:
20160

21-
1. Clone the repository
22-
2. Copy the `.env.example` to `.env` and update the values.
23-
2.1. Run `docker compose up -d`
24-
2.2. Run migrations with `docker compose run --rm app uv run alembic upgrade head`
25-
3. Check http://localhost:8000/docs for the Swagger docs in your browser
26-
4. Run `docker compose down` to stop the service
161+
- ✅ Set strong database credentials (`POSTGRES_USER`, `POSTGRES_PASSWORD`)
162+
- ✅ Configure appropriate rate limits
163+
- ✅ Set `APP_DEBUG=false` and `APP_RELOAD=false`
164+
- ✅ Configure trusted hosts properly (`TRUSTED_HOSTS`)
165+
- ✅ Set up proper CORS domains (`APP_CORS_DOMAINS`)
166+
- ✅ Use a secure bypass token (`APP_BYPASS_TOKEN`)
167+
- ✅ Configure minimum storage requirements (`APP_MIN_STORAGE_MB`)
168+
- ✅ Set appropriate worker count (`APP_WORKERS`)

0 commit comments

Comments
 (0)