# How-To Guides

[Home](./Home.md)

Welcome to the How-To Guides for RSS Proxy Transformer. Below are several guides to help you setup, deploy, and troubleshoot the application.

## 1. Environment Setup
- Ensure Python 3.7+ is installed.
- Clone the repository and install the dependencies:
  ```bash
  git clone https://github.com/Kenya-West/rss-proxy-transformer.git
  cd rss-proxy-transformer
  pip install -r requirements.txt
  ```

## 2. Running the Application
- Start the application locally:
  ```bash
  python app.py
  ```
- Access the feed at: `http://localhost:5000/feed`

## 3. Docker Deployment
### Using Dockerfile
- Build and run using Docker:
  ```bash
  docker build -t rss-proxy-transformer . 
  docker run -p 5000:5000 rss-proxy-transformer
  ```

### Using Docker Compose
- For development:
  ```bash
  docker-compose -f docker-compose.dev.yml up -d
  ```
- For production:
  ```bash
  docker-compose up -d
  ```

## 4. Configuration via Environment Variables
- Configure via the `.env` file:
  - `FEED_URL`: URL of the RSS feed.
  - `FEED_ENCODING`: (Optional) e.g. "windows-1251"
  - `TRANSFORM_RULES`: JSON array of rules.
- See [.env.example](../.env.example) for reference.

## 5. Adding Transformation Rules
- Transformation rules are applied to specific XML fields:
  - Example rule for `<link>`:
    ```json
    [
      {
        "field": "link",
        "regex": "^(https?://.*)$",
        "replacement": "https://proxy.example.com/?url=$1"
      }
    ]
    ```
- Update the `TRANSFORM_RULES` in your environment configuration.

## 6. Debugging and Troubleshooting
- Set `LOG_LEVEL=DEBUG` in your environment or `.env` file.
- Check logs in the terminal for detailed error messages.
- Common issues:
  - Incorrect `FEED_URL`
  - XML parsing errors (ensure valid XML feed)
  - Regex errors in transformation rules

## 7. Advanced Deployment and Customization
- **Cloud Deployment:** Deploy on Heroku, AWS, or any platform that supports Docker.
- **Caddy Reverse Proxy:** Refer to the [Caddy Docker Compose](../examples/caddy/docker-compose.yml) file for reverse proxy configuration.
- **SSL & Domain Routing:** Configure your domain settings in the `.env` file.

For further details, consult the [README.md](../README.md) or open an issue on GitHub.