# youtube-video-claiming
A collection of PHP scripts and cron jobs that automate video claiming for partnered YouTube channels. application_family: php-monolith

This project uses Docker multi-stage builds for development, testing, deployment, and one-time OAuth bootstrapping.

## Prerequisites
- Docker and Docker Compose
- GitHub authentication token set in `GITHUB_AUTH` environment variable
- Google OAuth client configured for YouTube APIs
- AWS credentials (for queue processing)

## Services Overview

### 1. OAuth Bootstrap (ONE-TIME SETUP)

⚠️ **This is a manual, one-time process required before any YouTube API calls can work.**

The OAuth bootstrap service is used to:

* Perform interactive Google OAuth login
* Obtain and store the refresh token
* Cache the initial access token
* Enable all future YouTube API calls to refresh tokens automatically (no user intervention)

**Start OAuth bootstrap**
```bash
docker compose up oauth-bootstrap
```

Then open in your browser:
```
http://localhost:8080/YoutubeAuthManually.php
```

**Flow**

1. Click "Connect Me to API"
2. Sign in to the Google account that owns / manages the YouTube partner account
3. Approve requested scopes
4. Token is saved to database and cache
5. Script exits successfully

✅ **After this succeeds once, this service should never be run again.**

**Important notes**

* Requires browser interaction (cannot run in Jenkins/CI)
* Depends on Memcache being healthy
* Must use a redirect URI registered in Google Cloud Console
* Should be removed or access-restricted after success

### 2. Activities Queue Population

Runs the activities queue population script with Memcache dependency:
```bash
docker compose up activities-q-population
```

This service:
- Depends on Memcache being healthy before starting
- Auto-restarts unless manually stopped
- Uses the stored OAuth refresh token
- Requires AWS credentials in environment variables

### Memcache
Memcache service for caching. Starts automatically with health checks:
```bash
docker compose up memcache
```

## Development Commands

### Update composer.lock
After adding or updating php packages, you need to re-generate `composer.lock`.

```bash
docker compose run --rm --build composer-update
```

### Unit Tests & Linting
Build and run unit tests and linters:
```bash
docker compose run --rm --build unit-lint
```

#### Fix (fixable) Style Issues Automatically
To automatically fix fixable style issues, run the format service. This will apply formatting fixes to all eligible files in the src/ folder:
```bash
docker compose run --rm --build format
```

## Environment Variables

### Required for activities-q-population:
- `GITHUB_AUTH` - GitHub authentication token (set as environment variable)
- `AWS_ACCESS_KEY_ID` - AWS access key
- `AWS_SECRET_ACCESS_KEY` - AWS secret key
- `AWS_SESSION_TOKEN` - AWS session token
- `AWS_REGION` - AWS region

### Optional:
- `.env` file can be created for additional configuration

## Running Services

### Start all services
```bash
docker compose up
```

### Start a specific service
```bash
docker compose up -d activities-q-population
```

### Stop everything
```bash
docker compose down
```

### View logs
```bash
docker compose logs -f activities-q-population
```

## ⚠️ Security & Operational Notes

* OAuth bootstrap must be run only once
* Never commit OAuth tokens to git
* Never expose `YoutubeAuthManually.php` publicly after bootstrap
* Jenkins/CI must use refresh-token flow only
* Re-running OAuth bootstrap may invalidate existing refresh tokens

## Typical Setup Order (IMPORTANT)

1. **Start Memcache**
```bash
docker compose up memcache
```

2. **Run OAuth bootstrap (once)**
```bash
docker compose up oauth-bootstrap
```

3. **Verify token is saved successfully**

4. **Start queue processing**
```bash
docker compose up activities-q-population
```