# 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/