links/README.md

# 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
- Advanced search capabilities
- API access
- Asynchronous page processing

## Installation

### Using Docker (Recommended)

1. Prerequisites:
   - Docker
   - Docker Compose

2. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/url-manager.git
   cd url-manager
   ```

3. Build and start services:
   ```bash
   ./docker.sh build
   ./docker.sh start
   ```

The application will be available at `http://localhost:8000`

### Docker Management Commands

- Start all services:
  ```bash
  ./docker.sh start
  ```

- Stop all services:
  ```bash
  ./docker.sh stop
  ```

- Restart services:
  ```bash
  ./docker.sh restart
  ```

- View logs:
  ```bash
  ./docker.sh logs
  ```

- Run database migrations:
  ```bash
  ./docker.sh migrate
  ```

- Create new migrations:
  ```bash
  ./docker.sh makemigrations
  ```

- Access Django shell:
  ```bash
  ./docker.sh shell
  ```

### Docker Services

The application runs the following services:

- `web`: Django web server (port 8000)
- `celery_worker`: Processes background tasks
- `celery_beat`: Schedules periodic tasks
- `redis`: Message broker and result backend

### Manual Installation

If you prefer not to use Docker:

1. Install Python 3.12 and Redis

2. Install uv:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

3. Install dependencies:
   ```bash
   uv pip install -r requirements.txt
   ```

4. Run migrations:
   ```bash
   python manage.py migrate
   ```

5. Start the development server:
   ```bash
   ./run_server.sh
   ```

6. Start Celery worker:
   ```bash
   ./worker.sh
   ```

7. Start Celery beat:
   ```bash
   ./celery_beat.sh
   ```

## Usage

### Managing Links

1. Create a new link:
   - Visit `/create/`
   - Enter the original URL and desired alias
   - For template links, use `{param}` syntax

2. Access a link:
   - Use `http://localhost:8000/your-alias`
   - For template links: `http://localhost:8000/your-alias/parameter`

### Managing Pages

1. Create a new page:
   - Visit `/ui/pages/new/`
   - Enter the URL
   - Title and summary will be automatically extracted

2. View all pages:
   - Visit `/ui/pages/`

### API Access

The application provides a REST API:

- List pages: `GET /api/pages/`
- Create page: `POST /api/pages/`

Example:

## Monitoring Celery Tasks

The application includes Flower for monitoring Celery tasks. You can access it in two ways:

1. Direct access:
   - Visit `http://localhost:5555` in your browser

2. Using management script:
   ```bash
   ./docker.sh flower
   ```

Flower provides:
- Real-time monitoring of Celery tasks
- Task progress and history
- Worker status and statistics
- Error tracking
- Task graphs and charts

### Monitoring Features

1. View all tasks:
   - Active tasks
   - Scheduled tasks
   - Failed tasks
   - Success rate

2. Worker information:
   - Status
   - Resource usage
   - Queue length

3. Task details:
   - Arguments
   - Start time
   - Runtime
   - Result
   - Stack traces for failed tasks


## Why we have `core` folder and what it is?

The core folder is the Django project's root configuration directory, created when you first run django-admin startproject core. It serves several essential purposes:
Project-wide settings (settings.py):
Database configuration
Installed apps
Middleware
Static/media files settings
Other global settings
Root URL configuration (urls.py):
Main URL routing
Admin site URLs
Including app-specific URLs
3. WSGI/ASGI configuration:
For production deployment
Server integration
Celery configuration (celery.py):
Project-wide Celery settings
Task discovery
We can't completely remove it because Django requires this project-level configuration. The links folder is an app within the project, and you could have multiple apps in one project.
Think of it this way:
core/ = Project configuration (can contain multiple apps)
links/ = One specific app's code
This separation allows you to:
1. Have multiple apps in one project
Reuse apps across different projects
Keep project-wide settings separate from app-specific code
If you want to simplify, you could rename core to something shorter like config or core, but you can't eliminate it entirely as it's a fundamental part of Django's project structure.
Would you like me to show you how to rename it to something shorter and cleaner?

## Development

### Using uv for Dependency Management

uv is a fast Python package installer and resolver. To add new dependencies:

```bash
uv pip


### Favicon

This favicon was generated using the following font:

- Font Title: Zen Tokyo Zoo
- Font Author: undefined
- Font Source: https://fonts.gstatic.com/s/zentokyozoo/v7/NGSyv5ffC0J_BK6aFNtr6sRv8a1uRWe9amg.ttf
- Font License: undefined)