diff --git a/README.md b/README.md
index 860ad58..6544e96 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,182 @@
 # q2dropzone
 
+Aplikacja do udostępniania plików z obsługą dużych uploadów (do 6 GB) przez protokół **tus** (resumable uploads).
+
+Stack: **Go 1.23** (backend) · **Vue 3 + Vite** (frontend) · **PostgreSQL 16** · **Nginx** · **Docker Compose**
+
+---
+
+## Wymagania
+
+| Narzędzie | Wersja |
+|-----------|--------|
+| Docker + Docker Compose | 24+ |
+| Go | 1.23+ (tylko tryb deweloperski) |
+| Node.js | 20+ (tylko tryb deweloperski) |
+
+---
+
+## Szybki start — Docker Compose (zalecane)
+
+### 1. Zmienne środowiskowe
+
+```bash
+cp .env.example .env
+```
+
+Edytuj `.env` — zmień co najmniej hasła i klucz JWT:
+
+```dotenv
+DB_PASSWORD=silne_haslo
+JWT_SECRET=losowy_ciag_min_32_znakow
+```
+
+### 2. Zbuduj i uruchom
+
+```bash
+docker compose up --build
+```
+
+Nginx nasłuchuje na portach **80** i **443**.
+
+> **Uwaga:** Domyślna konfiguracja Nginx (`nginx/conf.d/dropzone.conf`) przekierowuje HTTP → HTTPS i wymaga certyfikatów SSL w `nginx/certs/`. Lokalnie możesz uprościć konfigurację do samego HTTP — patrz sekcja [Nginx lokalnie](#nginx-lokalnie).
+
+### 3. Wolumen dyskowy
+
+Backend montuje `/mnt/dysk` jako katalog plików. Lokalnie możesz podmienić tę ścieżkę w `docker-compose.yml`:
+
+```yaml
+volumes:
+  - ./diskroot:/mnt/dysk
+```
+
+i utworzyć katalog:
+
+```bash
+mkdir -p diskroot/public
+```
+
+---
+
+## Tryb deweloperski (bez Dockera)
+
+### 1. Baza danych (PostgreSQL przez Docker)
+
+```bash
+docker compose up postgres -d
+```
+
+Baza jest dostępna na `localhost:15432`.
+
+### 2. Backend
+
+```bash
+cp .env.example .env
+# Uzupełnij .env — DATABASE_URL już wskazuje na localhost:15432
+
+cd backend
+go run ./cmd/server
+```
+
+Serwer startuje na `http://localhost:8080`.
+
+Jeśli zmienna `DISK_ROOT` nie jest ustawiona, backend przechowuje pliki w `./diskroot` (względem katalogu startowego).
+
+### 3. Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Vite startuje na `http://localhost:5173` i automatycznie proxy `/api/*` → `http://localhost:8080`.
+
+---
+
+## Nginx lokalnie
+
+Aby pominąć HTTPS lokalnie, zamień zawartość `nginx/conf.d/dropzone.conf` na:
+
+```nginx
+server {
+    listen 80;
+    server_name localhost;
+
+    client_max_body_size 6g;
+
+    location / {
+        root /app/frontend/dist;
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        proxy_pass http://backend:8080;
+        proxy_buffering off;
+        proxy_request_buffering off;
+    }
+
+    location /files/ {
+        proxy_pass http://backend:8080;
+        proxy_buffering off;
+        proxy_request_buffering off;
+        proxy_http_version 1.1;
+    }
+}
+```
+
+Następnie zbuduj frontend i uruchom cały stack:
+
+```bash
+cd frontend && npm install && npm run build && cd ..
+docker compose up --build
+```
+
+Aplikacja będzie dostępna na `http://localhost`.
+
+---
+
+## Zmienne środowiskowe
+
+| Zmienna | Opis | Domyślnie (lokalnie) |
+|---------|------|----------------------|
+| `DB_NAME` | Nazwa bazy danych | `dropzone` |
+| `DB_USER` | Użytkownik bazy | `dropzone` |
+| `DB_PASSWORD` | Hasło bazy | — |
+| `DATABASE_URL` | DSN PostgreSQL (backend poza Dockerem) | `postgres://dropzone:...@localhost:15432/dropzone` |
+| `PORT` | Port backendu | `8080` |
+| `JWT_SECRET` | Sekret do podpisywania tokenów JWT (min. 32 znaki) | — |
+| `DISK_ROOT` | Katalog główny plików na dysku | `./diskroot` |
+| `NGINX_ACCEL` | Włącza `X-Accel-Redirect` (tylko w Nginx) | `false` |
+
+---
+
+## Struktura projektu
+
+```
+q2dropzone/
+├── backend/          # Go — API REST, obsługa uploadów tus, JWT
+│   ├── cmd/server/   # punkt wejścia (main.go)
+│   └── internal/     # auth, files, middleware, admin
+├── frontend/         # Vue 3 + Vite + Tailwind + Uppy
+├── nginx/conf.d/     # konfiguracja Nginx
+├── postgres/init/    # schemat SQL (uruchamiany raz przy pierwszym starcie)
+├── scripts/          # backup_db.sh, deploy.sh, dem_parser.py
+├── docker-compose.yml
+└── .env.example
+```
+
+---
+
+## Pierwsze logowanie
+
+Schemat bazy (`postgres/init/01_schema.sql`) tworzy tylko tabelę `users`. Konto admina należy dodać ręcznie po pierwszym uruchomieniu bazy:
+
+```bash
+# Wejdź do kontenera bazy
+docker exec -it dropzone_postgres psql -U dropzone dropzone
+
+# Wstaw admina (hasło zahashuj bcryptem lub użyj skryptu pomocniczego)
+INSERT INTO users (username, password, role)
+VALUES ('admin', '<bcrypt_hash>', 'admin');
+```