mirror of
https://github.com/wahyd4/links.git
synced 2026-08-09 05:06:16 +10:00
132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# URL Manager
|
|
|
|
A URL management tool that helps you organize and access your links efficiently.
|
|
|
|
## Features
|
|
|
|
- Create and manage short links
|
|
- Template links with dynamic parameters
|
|
- Bookmark pages with automatic title and summary extraction
|
|
- Screenshot capture for bookmarked pages
|
|
- Advanced search capabilities
|
|
- REST API access
|
|
- In-process background task scheduling (APScheduler)
|
|
- Network security scanner (NetScan)
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.12+
|
|
- [uv](https://github.com/astral-sh/uv) — fast Python package manager
|
|
- [just](https://github.com/casey/just) — command runner (`brew install just`)
|
|
- Docker + Docker Compose (for containerised setup)
|
|
|
|
## Quick Start (Local)
|
|
|
|
```bash
|
|
# 1. Install dependencies and apply migrations
|
|
just install
|
|
|
|
# 2. Install Playwright browsers (for screenshot capture)
|
|
just install-browsers
|
|
|
|
# 3. Run the full stack (Django + Tailwind watcher)
|
|
just dev-all
|
|
```
|
|
|
|
The app will be available at **http://localhost:8000**
|
|
|
|
> Run `just` (no arguments) to see all available recipes.
|
|
|
|
## Local Development Commands
|
|
|
|
| Recipe | Description |
|
|
|---|---|
|
|
| `just dev` | Run Django server + Tailwind together |
|
|
| `just tailwind` | Run Tailwind CSS watcher (standalone) |
|
|
| `just migrate` | Apply pending migrations |
|
|
| `just makemigrations` | Generate new migrations |
|
|
| `just shell` | Open Django shell |
|
|
| `just dbshell` | Open raw DB shell |
|
|
| `just superuser` | Create a superuser |
|
|
| `just build-css` | Build minified Tailwind CSS |
|
|
| `just collectstatic` | Collect static files |
|
|
| `just test` | Run tests |
|
|
| `just compilemessages` | Compile i18n translation files |
|
|
| `just makemessages` | Extract translatable strings (zh_Hans) |
|
|
|
|
## Docker Commands
|
|
|
|
| Recipe | Description |
|
|
|---|---|
|
|
| `just docker-build` | Build images |
|
|
| `just docker-start` | Start all services (detached) |
|
|
| `just docker-stop` | Stop all services |
|
|
| `just docker-restart` | Restart services |
|
|
| `just docker-logs` | Tail logs (all services) |
|
|
| `just docker-logs web` | Tail logs for a specific service |
|
|
| `just docker-shell` | Shell into the web container |
|
|
| `just docker-migrate` | Run migrations inside Docker |
|
|
| `just docker-static` | Collect static files inside Docker |
|
|
| `just docker-rebuild web` | Rebuild and restart a specific service |
|
|
|
|
### Docker Services
|
|
|
|
- `web` — Django server on port 8000 (APScheduler runs in-process)
|
|
- `node` — Tailwind CSS compiler
|
|
|
|
## Usage
|
|
|
|
### Managing Links
|
|
|
|
1. Create a new link at `/create/`
|
|
2. Access a link at `http://localhost:8000/your-alias`
|
|
3. For template links use `{param, default=value}` syntax in the URL
|
|
|
|
### Managing Pages (Bookmarks)
|
|
|
|
1. Add a bookmark at `/ui/pages/new/` — title and summary are auto-extracted
|
|
2. Screenshots are captured automatically in the background
|
|
3. View all bookmarks at `/ui/pages/`
|
|
|
|
### Network Scanner (NetScan)
|
|
|
|
Available at `/ui/netscan/`. Create a scan profile to automatically monitor your home network for security issues (router exposure, DNS, TLS certs, camera access).
|
|
|
|
### API
|
|
|
|
- List pages: `GET /api/pages/`
|
|
- Full API docs: `/ui/api-docs/`
|
|
|
|
## Architecture
|
|
|
|
```
|
|
core/ — Django project config, APScheduler setup
|
|
links/ — Main app: links, pages, tags, posts, collections
|
|
netscan/ — Network security scanner
|
|
templates/ — Base HTML templates
|
|
```
|
|
|
|
Background tasks (screenshot capture, page metadata extraction, network scans) run via **APScheduler** in-process — no separate worker or Redis needed.
|
|
|
|
## Dependencies
|
|
|
|
Managed with `uv` via `pyproject.toml`.
|
|
|
|
```bash
|
|
# Add a new package
|
|
uv add package-name
|
|
|
|
# Sync environment from lockfile
|
|
uv sync
|
|
```
|
|
|
|
## Favicon
|
|
|
|
Generated using the Zen Tokyo Zoo font (https://fonts.gstatic.com/s/zentokyozoo/).
|
|
|
|
## Image Resizing (Cloudflare)
|
|
|
|
- Bind a custom domain
|
|
- Enable image resizing: https://developers.cloudflare.com/images/transform-images/
|
|
|