# How to Configure ReClip Using Environment Variables: A Complete Guide

> Learn how to configure ReClip using environment variables. This guide covers setting PORT and HOST variables for your Flask application runtime.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: how-to-guide
- Published: 2026-09-03

---

**ReClip can be configured at runtime using two environment variables—`PORT` and `HOST`—that are read via `os.environ.get()` in the Flask application entry point.**

ReClip is an open-source image search tool that uses CLIP embeddings to find visually similar images. The repository exposes a web interface through a Flask application, and you can customize its network binding without modifying any code by using standard environment variables. This guide covers exactly which variables are supported, where they are read in the source code, and how to use them in local development or Docker deployments.

## Environment Variables Supported by ReClip

ReClip reads two environment variables during application startup in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py):

| Variable | Default Value | Purpose |
|----------|---------------|---------|
| `PORT` | `8899` | TCP port for the web server |
| `HOST` | `127.0.0.1` | Network interface to bind to |

These defaults ensure the application runs securely in local development mode, listening only on the loopback interface.

## Where Environment Variables Are Read in the Source Code

The configuration logic is implemented in **[`app.py`](https://github.com/averygan/reclip/blob/main/app.py)** at lines 208–210:

```python

# app.py

port = int(os.environ.get("PORT", 8899))
host = os.environ.get("HOST", "127.0.0.1")
app.run(host=host, port=port)

```

The code uses Python's standard `os.environ.get()` with fallback defaults, making the variables optional. Changes take effect immediately on the next application start—no rebuild or reinstallation is required.

## Running ReClip Locally with Custom Environment Variables

For local development, export variables in your shell before starting the application:

```bash

# Bind to all interfaces and use port 8080

export PORT=8080
export HOST=0.0.0.0

# Start the Flask server

python app.py

```

The server will now be accessible from other machines on your network at `http://<your-ip>:8080`.

You can also set variables inline for a single command:

```bash
PORT=3000 HOST=0.0.0.0 python app.py

```

## Docker and Docker Compose Configuration

The repository includes a [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml) file that forwards environment variables to the container. The standard pattern uses shell variable substitution with defaults:

```yaml
services:
  reclip:
    build: .
    environment:
      - PORT=${PORT}
      - HOST=${HOST}
    ports:
      - "${PORT:-8899}:8899"

```

### Using a `.env` File

Create a `.env` file in the project root:

```dotenv
PORT=8080
HOST=0.0.0.0

```

Docker Compose automatically loads this file, so running `docker-compose up` will apply your configuration:

```bash
docker-compose up -d

```

The container's internal port 8899 is mapped to your specified host port (8080 in this example).

### Runtime Overrides Without a `.env` File

Pass variables directly to the Docker Compose command:

```bash
PORT=3000 HOST=0.0.0.0 docker-compose up -d

```

Or export them first:

```bash
export PORT=5000
export HOST=0.0.0.0
docker-compose up -d

```

## Key Files for Environment Configuration

Understanding these source files helps when troubleshooting or extending ReClip's configuration:

- **[`app.py`](https://github.com/averygan/reclip/blob/main/app.py)** — Main Flask application entry point where `PORT` and `HOST` are read from the environment
- **[`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml)** — Service definition that propagates environment variables into the container
- **`Dockerfile`** — Container build instructions that install dependencies and set the working directory

## Common Configuration Scenarios

### Expose ReClip on a Custom Port

Use when port 8899 is already occupied on your system:

```bash
PORT=9000 python app.py

```

### Make ReClip Accessible from Other Devices

Required for remote access or when running in a container on a server:

```bash
HOST=0.0.0.0 PORT=8080 python app.py

```

### Production Deployment with Docker

Combine both variables with Docker Compose for a production-ready setup:

```dotenv

# .env

PORT=80
HOST=0.0.0.0

```

Then run with a reverse proxy (nginx, Traefik, etc.) handling SSL termination.

## Summary

- **Two variables control ReClip's network behavior**: `PORT` (default 8899) and `HOST` (default 127.0.0.1)
- **Configuration happens in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py)** via `os.environ.get()` with sensible defaults
- **Local development**: Export variables in your shell or pass them inline
- **Docker deployments**: Use a `.env` file or environment blocks in [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml)
- **No code changes required**: The application reads these values at startup each time

## Frequently Asked Questions

### What environment variables does ReClip support?

ReClip supports exactly two environment variables: `PORT` for the TCP port and `HOST` for the bind address. These are read in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) using `os.environ.get()` with defaults of 8899 and 127.0.0.1 respectively. No other runtime configuration is currently implemented in the codebase.

### Can I use a `.env` file with ReClip?

Yes. When running with Docker Compose, create a `.env` file in the project root containing `PORT` and `HOST` values. Docker Compose automatically loads this file and substitutes variables into the [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/docker-compose.yml) service definition. For local Python execution, you would need to load the file manually with a tool like `python-dotenv` or export variables yourself.

### Why does ReClip default to 127.0.0.1 instead of 0.0.0.0?

The default `HOST=127.0.0.1` is a security-conscious choice for local development, preventing accidental exposure of the development server to the network. Production deployments or containerized environments should explicitly set `HOST=0.0.0.0` to allow external connections.

### Do I need to rebuild the Docker image after changing environment variables?

No. Environment variables are read at container runtime, not build time. Simply restart the container with `docker-compose up` after modifying your `.env` file or shell exports. The image itself remains unchanged.