Local development

Set up and run the Exchange platform on your local machine for development

This guide will help you set up the Exchange platform for local development. The platform consists of multiple Rust services that work together to provide a high-performance cryptocurrency exchange.

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (1.87 or later) - Install Rust
• Docker and Docker Compose - Install Docker
• PostgreSQL (via Docker)
• Redis (via Docker)
• Git - Install Git

Quick start

1. Clone the repository

   Clone the Exchange repository from GitHub:

   git clone https://github.com/jogeshwar01/exchange.git
   cd exchange
   
2. Configure environment variables

   Copy the example environment file and configure your local database credentials:

   cp .env.example .env
   

   Edit the .env file with your local configuration. For local development, you can use:

   PG__USER=root
   PG__PASSWORD=root
   PG__HOST=localhost
   PG__PORT=5000
   PG__DBNAME=exchange-db
   PG__POOL_MAX_SIZE=16
   
   DATABASE_URL=postgres://root:root@localhost:5000/exchange-db
   
3. Start infrastructure services

   Start PostgreSQL and Redis using Docker Compose:

   cd docker
   docker compose -f docker-compose.yml up -d
   

   This will start:

   • PostgreSQL on port 5000 (mapped from container port 5432)
   • Redis on port 6380 (mapped from container port 6379)

   The database will persist data in ./docker/postgres-data and Redis in ./docker/redis-data.

4. Build the project

   Return to the project root and build all services:

   cd ..
   cargo build
   

   This will compile all workspace members including:

   • router - REST API server
   • engine - Order matching engine
   • ws-stream - WebSocket streaming service
   • db-processor - Database operations processor
5. Run the application

   Start the main application:

   cargo run
   

   Or run specific services individually:

   Router (REST API)

   cargo run --bin router
   

Service ports

When running locally, the services use the following ports:

Service	Port	Description
Router	8080	REST API endpoints
Engine	8081	Order matching engine
WebSocket	4000	Real-time market data streams
DB Processor	8083	Database operations
PostgreSQL	5000	Database (mapped from 5432)
Redis	6380	Pub/sub and caching (mapped from 6379)

Development workflow

Running tests

cargo test

Code formatting

The project uses rustfmt for code formatting:

cargo fmt

Linting

Run Clippy for linting:

cargo clippy

Database migrations

The project uses SQLx for database migrations. Migrations are located in:

crates/sqlx_postgres/migrations/

To apply migrations:

sqlx migrate run

SQLx requires DATABASE_URL to be set in your environment or .env file.

Troubleshooting

Port already in use

If you see errors about ports being in use, check what’s running:

lsof -i :8080  # Check if router port is in use
lsof -i :5000  # Check if PostgreSQL port is in use

Stop any conflicting services or change the ports in your configuration.

Database connection errors

If you can’t connect to PostgreSQL:

1. Verify Docker containers are running:

   docker ps
   

2. Check container logs:

   docker logs exchange-postgres
   

3. Ensure your .env file has correct credentials matching the Docker setup.

Redis connection errors

If Redis connection fails:

1. Check Redis is running:

   docker ps | grep redis
   

2. Test Redis connection:

   docker exec -it exchange-redis redis-cli ping
   

SQLX offline mode

If you encounter SQLx compile-time verification errors:

# Set offline mode
export SQLX_OFFLINE=true
cargo build

Or prepare the query cache:

SQLX_OFFLINE=false cargo sqlx prepare --workspace

Clean rebuild

If you encounter build issues, try a clean rebuild:

cargo clean
cargo build

Hot reload

For faster development iterations, you can use cargo-watch:

# Install cargo-watch
cargo install cargo-watch

# Run with auto-reload
cargo watch -x run

Next steps

• Learn about Docker deployment for containerized development
• Explore the API documentation
• Read about production deployment