A complete walkthrough for setting up Claude Code - from Docker installation to API usage. This open-source project lets you use Claude AI through Amazon Q Developer accounts, providing a cost-effective alternative to the official API. --- ## Table of Contents - [Install Docker](#install-docker) - [Windows 10/11](#1-windows-1011) - [macOS](#2-macos-intel--apple-silicon) - [Ubuntu / Debian](#3-ubuntu--debian) - [CentOS / RHEL / Fedora](#4-centos--rhel--fedora) - [Arch Linux](#5-arch-linux) - [Verify Installation](#6-verify-installation) - [Configuration](#configuration) - [Run Docker](#run-docker) - [Open the Project](#open-the-project) - [Adding Your First Account](#adding-your-first-account) - [API Usage](#api-usage) - [Troubleshooting](#troubleshooting) --- Claude Code is an open-source project that provides Claude API access using Amazon Q Developer accounts. It's perfect for developers who want to integrate Claude's capabilities into their applications without paying for the official API. # Install Docker ## **1. Windows 10/11** ### **Using Docker Desktop (recommended)** 1. Go to Docker's official download page: 2. Download **Docker Desktop for Windows**. 3. Run the installer: - Enable **WSL 2** when prompted. - Restart if required. 4. Launch Docker Desktop → confirm it shows "Docker is running." **Requirements:** - Windows 10/11 64-bit - WSL 2 enabled - Hardware virtualization enabled in BIOS --- ## **2. macOS (Intel & Apple Silicon)** ### **Using Docker Desktop** 1. Download Docker Desktop for macOS: 2. Choose the correct version: - Intel Macs - Apple Silicon (M1/M2/M3/M4) 3. Open the `.dmg` → drag Docker to Applications. 4. Launch Docker Desktop → allow permissions. **Requirements:** - macOS 12+ recommended - Admin privileges --- ## **3. Ubuntu / Debian** ### **Install Docker Engine (CLI only)** ### **Step 1 — Remove old versions** ```bash sudo apt remove docker docker-engine docker.io containerd runc ``` ### **Step 2 — Add Docker's official repo** ```bash sudo apt update sudo apt install ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null ``` ### **Step 3 — Install Docker** ```bash sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` ### **Step 4 — (Optional) Run Docker without sudo** ```bash sudo usermod -aG docker $USER ``` > **Note:** Log out and back in for this to take effect. --- ## **4. CentOS / RHEL / Fedora** ### Install Docker Engine ### Remove old versions ```bash sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine ``` ### Add repo ```bash sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo ``` ### Install ```bash sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo systemctl enable --now docker ``` --- ## **5. Arch Linux** ### **Using pacman** ```bash sudo pacman -S docker docker-compose sudo systemctl enable --now docker ``` --- ## **6. Verify Installation** Run: ```bash docker --version docker compose version docker run hello-world ``` You should see version information and a message confirming Docker is working. --- # Configuration Before running Claude Code, you need to create a configuration file. ## **1. Create Environment File** The `.env` file stores your configuration settings. Keep this file secure and never commit it to version control! Create a `.env` file in the project root directory: ## **2. Configure Environment Variables** Edit the `.env` file with your preferred settings: ```bash # API Keys (comma-separated, leave empty for development mode) # When empty, any API key will work (for local testing) API_KEYS="" # Admin password for web console (CHANGE THIS!) ADMIN_PASSWORD="your-secure-password" # Maximum error count before auto-disabling an account MAX_ERROR_COUNT=100 # HTTP proxy (optional, for corporate networks) HTTP_PROXY="" # Enable web console (default: true) ENABLE_CONSOLE="true" # Frontend URL for redirects FRONTEND_URL="http://localhost:3000" # Server port PORT=8000 # Database URL (leave empty for SQLite - recommended for most users) # PostgreSQL: DATABASE_URL="postgresql://user:password@host:5432/dbname" # MySQL: DATABASE_URL="mysql://user:password@host:3306/dbname" DATABASE_URL="" ``` ### Configuration Options Explained | Variable | Description | Default | | ----------------- | ---------------------------------------------------------------------- | ------------------------- | | `API_KEYS` | Comma-separated list of allowed API keys. Leave empty for open access. | `""` | | `ADMIN_PASSWORD` | Password to access the admin dashboard | `"admin"` | | `MAX_ERROR_COUNT` | Account auto-disables after this many consecutive errors | `100` | | `HTTP_PROXY` | HTTP proxy URL for outbound requests | `""` | | `ENABLE_CONSOLE` | Enable/disable the web console | `"true"` | | `FRONTEND_URL` | URL where the frontend is hosted | `"http://localhost:3000"` | | `PORT` | Backend server port | `8000` | | `DATABASE_URL` | Database connection string (empty = SQLite) | `""` | --- # Run Docker ## **1. Clone the Repository** ## **2. Start the Docker Containers** Navigate to your project directory and run: This will: - Build the backend (FastAPI) and frontend (Next.js) images - Start both containers in detached mode - Create a persistent data volume for the SQLite database **Note:** First run may take several minutes to build the images. ## **3. Check Container Status** Verify that your containers are running: You should see output similar to: 8000/tcp claude-code-frontend-1 claude-code-frontend Up 2 minutes 0.0.0.0:3000->3000/tcp`} /> ## **4. View Container Logs** To monitor the containers' output: ```bash # View all logs docker compose logs -f # View backend logs only docker compose logs -f backend # View frontend logs only docker compose logs -f frontend ``` ## **5. Stop the Containers** When you need to stop the containers: ```bash docker compose down ``` ## **6. Restart the Containers** To restart after making changes: ```bash docker compose restart ``` Or to rebuild and restart: ```bash docker compose up -d --build ``` ## **7. Update to Latest Version** ```bash git pull origin main docker compose up -d --build ``` --- # Open the Project ## **1. Access the Web Interface** Once the containers are running, open your browser and navigate to: | Interface | URL | Description | | -------------------------- | -------------------------------------------------------------- | ------------------------------- | | **Frontend (Recommended)** | [http://localhost:3000](http://localhost:3000) | Modern Next.js dashboard | | **Backend API** | [http://localhost:8000](http://localhost:8000) | Basic interface & API endpoints | | **Health Check** | [http://localhost:8000/healthz](http://localhost:8000/healthz) | Container health status | ## **2. Login to Dashboard** 1. Open [http://localhost:3000](http://localhost:3000) 2. Enter your admin password (default: `admin`, or whatever you set in `.env`) 3. Click **Login** ## **3. Dashboard Overview** After logging in, you'll see the main dashboard with the following tabs: | Tab | Description | | -------------- | -------------------------------------------------------------- | | **Accounts** | Manage Amazon Q accounts - add, enable/disable, refresh tokens | | **URL Login** | Alternative method to add accounts via URL | | **Chat Test** | Built-in chat interface to test your Claude API setup | | **API Tokens** | Create and manage API tokens for programmatic access | | **Usage** | Monitor token usage, view analytics and usage patterns | --- # Adding Your First Account ## **Method 1: Device Authorization (Recommended)** 1. Go to the **Accounts** tab 2. Click **Add Account** 3. A device authorization code will appear 4. Click the authorization link or visit: 5. Enter the code and authorize 6. Return to the dashboard - your account will be added automatically ## **Method 2: URL Login** 1. Go to the **URL Login** tab 2. Follow the instructions to obtain a login URL 3. Paste the URL and submit 4. Your account will be added ## **Verify Account Status** After adding an account: - Check that the status shows **Enabled** - The account should show valid token expiry times - Use the **Chat Test** tab to verify the connection works --- # API Usage Once you have accounts configured, you can use Claude Code as a Claude API replacement. ## **Python (with Anthropic SDK)** ```python from anthropic import Anthropic client = Anthropic( base_url="http://localhost:8000", api_key="your-api-key" # Any key works if API_KEYS is empty ) message = client.messages.create( model="claude-sonnet-4", max_tokens=1024, messages=[ {"role": "user", "content": "Hello! How are you?"} ] ) print(message.content[0].text) ``` ```python with client.messages.stream( model="claude-sonnet-4", max_tokens=1024, messages=[{"role": "user", "content": "Write a short poem about coding"}] ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ``` ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ baseURL: 'http://localhost:8000', apiKey: 'your-api-key', }); const message = await client.messages.create({ model: 'claude-sonnet-4', max_tokens: 1024, messages: [{ role: 'user', content: 'Hello!' }], }); console.log(message.content[0].text); ``` ```bash curl -X POST http://localhost:8000/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: your-api-key" \ -d '{ "model": "claude-sonnet-4", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hello!"} ] }' ``` ## **Available API Endpoints** | Endpoint | Method | Description | | --------------------------- | ------ | ------------------------------------------------- | | `/v1/messages` | POST | Claude Messages API (streaming and non-streaming) | | `/v1/messages/count_tokens` | POST | Token counting endpoint | | `/api/status` | GET | System status check | | `/healthz` | GET | Health check endpoint | --- # Troubleshooting ## **Common Issues** ### Container won't start ```bash # Check logs for errors docker compose logs # Ensure ports aren't already in use lsof -i :3000 lsof -i :8000 # Try rebuilding docker compose down docker compose up -d --build ``` ### Permission denied errors ```bash # Ensure Docker can access project files sudo chown -R $USER:$USER . # Linux: Add user to docker group sudo usermod -aG docker $USER # Then log out and back in ``` ### Database errors ```bash # Reset the database rm -rf data/data.sqlite3 docker compose restart backend ``` ### Account authorization fails 1. Ensure your internet connection is working 2. Check if the device authorization URL is accessible 3. Try using the URL Login method instead 4. Check backend logs: `docker compose logs -f backend` ### Frontend can't connect to backend 1. Ensure both containers are running: `docker compose ps` 2. Check that backend is healthy: `curl http://localhost:8000/healthz` 3. View frontend logs: `docker compose logs -f frontend` ### API returns 401 Unauthorized 1. Check your `API_KEYS` setting in `.env` 2. If `API_KEYS` is set, ensure you're using one of the allowed keys 3. If empty, any API key should work ### High memory usage ```bash # Check container resource usage docker stats # Restart containers to free memory docker compose restart ``` ## **Getting Help** If you encounter issues not covered here: 1. Check the GitHub Issues: 2. Search for similar problems 3. Create a new issue with: - Your operating system - Docker version (`docker --version`) - Error messages from logs - Steps to reproduce --- # Advanced Configuration ## **Using an External Database** ### PostgreSQL ```bash # .env DATABASE_URL="postgresql://username:password@localhost:5432/claude_code" ``` ### MySQL ```bash # .env DATABASE_URL="mysql://username:password@localhost:3306/claude_code" ``` ## **Running Behind a Reverse Proxy (Nginx)** ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } location /v1/ { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 300s; proxy_buffering off; # Important for streaming } location /api/ { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` ## **Custom Docker Compose Override** Create a `docker-compose.override.yml` for local customizations: ```yaml services: backend: environment: - DEBUG=true ports: - '8080:8000' # Use different port frontend: ports: - '3001:3000' # Use different port ``` --- # Local Development (Without Docker) For development without Docker: ## **Backend** ```bash # Install Python dependencies pip install -e . # Run with auto-reload uvicorn src.main:app --reload --host 0.0.0.0 --port 8000 ``` ## **Frontend** ```bash cd frontend # Install dependencies npm install # Run development server npm run dev ``` --- # Quick Reference | Task | Command | | ---------------- | ------------------------------------------ | | Start containers | `docker compose up -d` | | Stop containers | `docker compose down` | | View logs | `docker compose logs -f` | | Restart | `docker compose restart` | | Rebuild | `docker compose up -d --build` | | Check status | `docker compose ps` | | Update | `git pull && docker compose up -d --build` | | URL | Purpose | | ----------------------------- | --------------------------- | | http://localhost:3000 | Frontend dashboard | | http://localhost:8000 | Backend API | | http://localhost:8000/healthz | Health check | | http://localhost:8000/docs | API documentation (Swagger) | --- ## Conclusion You now have a fully functional Claude Code installation running locally. You can: - Add multiple Amazon Q accounts for load balancing - Use it as a drop-in replacement for the official Claude API - Monitor usage through the web dashboard - Scale horizontally by adding more backend containers

Open Source Docker FastAPI Next.js

### Useful Resources **Docker Hub Repository:** ### About the Author --- _This guide is based on Claude Code, an open-source project. Always check the official repository for the latest updates and documentation._

Comments

Leave a Comment