x402proxy Developers

This section is for developers who want to contribute to x402proxy or run it locally for development.

Prerequisites

• Node.js 18+ and npm 9+

• Git (for cloning the repository)

Local Development Setup

1. Clone the Repository

git clone https://github.com/zachalam/x402proxy.git
cd x402proxy

2. Install Dependencies

npm install

3. Create Configuration File

cp custom-config.json config.json
# Edit config.json with your settings

Note: For local development, you'll need to update the config path in src/index.js or create a symlink, as the code expects /app/config.json by default (Docker path).

4. Run in Development Mode

npm run dev

This uses nodemon for hot reload, so changes to src/index.js will automatically restart the server.

5. Run in Production Mode

npm start

Development with Docker

Using Docker Compose

For a consistent development environment using Docker Compose:

1. Create a docker-compose.yml file:

   version: '3.8'
   services:
     x402proxy:
       image: ghcr.io/zachalam/x402proxy:latest
       ports:
         - "8080:8080"
       volumes:
         - ./custom-config.json:/app/config.json:ro

2. Start the service:

   docker-compose up -d

3. View logs:

   docker-compose logs -f

4. Stop the container:

   docker-compose down

The development Docker setup includes:

• Hot reload with nodemon (when using Dockerfile.dev)

• Source code mounted as volume

• Config file mounted from custom-config.json

Project Structure

x402proxy/
├── src/
│   └── index.js          # Main application file
├── docs/                 # GitBook documentation
├── web/                   # Website files
├── Dockerfile             # Production Docker image
├── Dockerfile.dev         # Development Docker image
├── docker-compose.yml     # Docker Compose configuration
├── package.json          # Node.js dependencies
└── custom-config.json    # Example configuration

Available Scripts

Script	Description
npm start	Run the application in production mode
npm run dev	Run with nodemon for hot reload
npm run lint	Run ESLint on source code

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test locally

5. Submit a pull request

Building Docker Images

Production Image

docker build -t x402proxy:latest -f Dockerfile .

Development Image

docker build -t x402proxy:dev -f Dockerfile.dev .

Environment Variables

Variable	Description	Default
PORT	Server port	8080
NODE_ENV	Environment mode	production
NODE_TLS_REJECT_UNAUTHORIZED	Disable SSL verification (dev only)	1

Testing

Currently, there are no automated tests. Manual testing can be done by:

1. Starting the server

2. Making requests to protected endpoints

3. Verifying payment flow

4. Checking proxy functionality

Troubleshooting Development Issues

Config File Not Found

If you see "Failed to load /app/config.json", you're running locally but the code expects the Docker path. Options:

1. Create a symlink: ln -s $(pwd)/config.json /app/config.json (requires sudo)

2. Modify src/index.js to use a local path for development

3. Use Docker for development instead

Port Already in Use

Change the port:

PORT=3000 npm run dev

Module Not Found

Ensure dependencies are installed:

npm install