Setup

This guide details the deployment and configuration processes for the URL Media Inspector infrastructure.

Requirements

• Node.js: v22.x or higher
• Docker: Docker Engine with Docker Compose V2 (for containerized deployment)
• Redis: Redis 7+ (included in Docker Compose)
• ffmpeg: Required for video/audio metadata extraction (included in Docker image)
• Network: Ability to make outbound requests to public IP ranges
• Memory: Minimum 512MB RAM recommended per instance

Docker Compose (Recommended)

The fastest way to deploy is via Docker Compose, which bundles the application, Redis, and all dependencies.

1. Clone and configure

git clone https://github.com/Karan09542/url-media-inspector.git
cd url-media-inspector/server

2. Set environment variables

Create a .env file in the server/ directory or export variables in your shell:

# Required for production
PUBLIC_API_URL=https://your-api-domain.com
WEBHOOK_SECRET=your-strong-secret
ADMIN_TOKEN=your-admin-token
REDIS_PASSWORD=your-redis-password

For local development, set PUBLIC_API_URL to your local address:

PUBLIC_API_URL=http://localhost:3000

Note: PUBLIC_API_URL controls the Swagger UI server URL and Content Security Policy connect-src directive. Without it, Swagger "Try it out" requests may be blocked by CSP in production.

3. Start the stack

docker compose up -d

This starts:

• url-media-inspector-app — the API server on port 3000
• url-media-inspector-redis — Redis for caching and job queues (internal only, not exposed to host)

4. Verify

curl http://localhost:3000/api/v1/inspect?profile=fast \
  -X POST -H "Content-Type: application/json" \
  -d '{"url": "https://images.unsplash.com/photo-example"}'

Swagger UI is available at: http://localhost:3000/api-docs

Updating

To deploy a new version:

docker compose pull
docker compose up -d

Local Development (without Docker)

For active development with hot-reloading:

cd server
npm install
npm run dev

The server starts on port 3000 using .env configuration with NODE_ENV=development.

Production Deployment

Reverse Proxy

Place the API behind a reverse proxy (e.g., Nginx) for:

• SSL/TLS termination
• Rate limiting
• Domain routing

Infrastructure Considerations

Caching

The service uses Redis for canonical resource caching to prevent redundant external URL fetching. Ensure your Redis instance has adequate memory for high-traffic scenarios.

Timeouts

The API enforces strict timeout limits on outbound requests. If inspecting large media files or URLs from slow domains, the API will intentionally fail to prevent holding open sockets.

Security Headers

The application uses Helmet for security headers including Content Security Policy. The CSP connect-src directive is automatically configured based on PUBLIC_API_URL to allow Swagger UI API execution.

Rate Limiting

Rate limiting is not enforced at the application level. It is highly recommended to place this API behind an API gateway or reverse proxy that handles rate limiting.