Link-Tracker-Server/readme_md.md

# Link Tracker API

A simple web service that tracks links to your client websites and provides reports for SEO indexing services.

## What This Does

This tool helps you:
- Track which pages link to your client websites
- Generate lists of URLs to submit to indexing services like colinkiri
- Keep track of which URLs you've already submitted

## Installation

### Step 1: Install Python

**On Mac:**
1. Open Terminal (press `Cmd + Space`, type "Terminal", press Enter)
2. Install Homebrew if you don't have it:
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
3. Install Python:
   ```bash
   brew install python
   ```

**On Windows:**
1. Go to https://python.org/downloads/
2. Download the latest Python version
3. Run the installer
4. **Important:** Check "Add Python to PATH" during installation
5. Open Command Prompt (press `Win + R`, type "cmd", press Enter)

### Step 2: Download the Project

1. Open Terminal (Mac) or Command Prompt (Windows)
2. Navigate to where you want to install the project:
   ```bash
   cd Desktop
   ```
3. Clone the project from GitHub:
   ```bash
   git clone https://git.peninsulaindustries.com/bryanb/Link-Tracker-Server.git
   cd link-tracker
   ```

### Step 3: Install Required Packages

**On Mac (Terminal):**
```bash
cd ~/Desktop/link-tracker
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

**On Windows (Command Prompt):**
```bash
cd %USERPROFILE%\Desktop\link-tracker
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

## Running the Server

**On Mac:**
```bash
cd ~/Desktop/link-tracker
source venv/bin/activate
python main.py
```

**On Windows:**
```bash
cd %USERPROFILE%\Desktop\link-tracker
venv\Scripts\activate
python main.py
```

You should see something like:
```
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
```

**The server is now running!** Keep this window open while you use the system.

## Getting Your URL Reports

### For Colinkiri Indexing Service

Open your web browser and go to:
```
http://localhost:8000/urls/for-colinkiri
```

This will show you a list of URLs, one per line, that you can copy and paste into colinkiri. **Important:** After you visit this URL, those pages are marked as "submitted" so they won't appear in future reports.

### For Other Indexing Services

Open your web browser and go to:
```
http://localhost:8000/urls/for-indexer
```

Same as above, but for a different indexing service.

## Updating to the Latest Version

When updates are available, you can easily update the project:

1. Stop the server (press `Ctrl + C` in the terminal)
2. Update the code:
   ```bash
   git pull origin main
   ```
3. Update any new dependencies:
   ```bash
   pip install -r requirements.txt
   ```
4. Restart the server:
   ```bash
   python main.py
   ```

**Note:** Your data (link_tracker.db file) will not be affected by updates.

## Stopping the Server

To stop the server, go back to your Terminal/Command Prompt window and press `Ctrl + C`.

## Troubleshooting

**"Command not found" errors:**
- Make sure Python is installed and added to your PATH
- Try using `python3` instead of `python` on Mac
- Try using `py` instead of `python` on Windows

**"Port already in use" error:**
- Another program is using port 8000
- Try changing the port in main.py (last line): `uvicorn.run(app, host="0.0.0.0", port=8001)`
- Then use `http://localhost:8001` instead of `http://localhost:8000`

**Can't access the URLs:**
- Make sure the server is running (you should see the "Uvicorn running" message)
- Check that you're using the correct URL: `http://localhost:8000`
- Try refreshing your browser

## Other Available Endpoints

These are for advanced users or developers:

### View All Captured Pages
```
http://localhost:8000/pages
```
Shows all pages that have been captured with link information.

### View Statistics
```
http://localhost:8000/stats
```
Shows overall statistics about captured pages and links.

### Search for Pages Linking to Specific URL
```
http://localhost:8000/search/linking-to?target_url=https://example.com
```
Find all pages that link to a specific URL.

### View Links for Specific Client
```
http://localhost:8000/clients/clientdomain.com/links
```
See all links pointing to a specific client domain.

### API Documentation
```
http://localhost:8000/docs
```
Interactive API documentation (for developers).

## Data Storage

The system automatically creates a file called `link_tracker.db` in the same folder as `main.py`. This file contains all your captured data. **Don't delete this file** unless you want to lose all your data.

## Support

If you run into issues:
1. Make sure Python is properly installed
2. Make sure you're in the correct folder when running commands
3. Check that the server is running before trying to access URLs
4. Try restarting the server if something seems stuck