Skip to main content

​
Overview

This guide walks you through setting up the Currency Converter API from scratch. You’ll configure environment variables, set up Docker containers, and obtain API keys from currency exchange providers.

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed
  • Git for cloning the repository
  • API keys from at least one currency provider (recommended: all three for redundancy)

​
Environment configuration

1

Clone the repository

Start by cloning the Currency Converter API repository:
git clone https://github.com/yourusername/currency-converter.git
cd currency-converter
2

Copy environment template

The repository includes an example environment file with all required variables:
cp .env.example .env
This creates your local .env file that you’ll customize with your specific configuration.
3

Configure environment variables

Open the .env file and configure the following sections:

​
Application settings

APP_NAME="Currency Converter Service"
VERSION="0.1.0"
DEBUG=true
ENVIRONMENT="development"

​
Server configuration

HOST="0.0.0.0"
PORT=8000

​
Database configuration

DATABASE_URL="postgresql://postgres:password@localhost:5432/currency_converter"
DATABASE_ECHO=false
When running with Docker Compose, replace localhost with the service name db in the DATABASE_URL.

​
Redis configuration

REDIS_URL="redis://localhost:6379/0"
CACHE_TTL=300  # 5 minutes in seconds

​
API provider settings

Configure your API keys for the currency exchange providers:
# Fixer.io
FIXERIO_API_KEY="your_fixer_api_key_here"

# OpenExchangeRates
OPENEXCHANGE_APP_ID="your_openexchange_app_id_here"

# CurrencyAPI
CURRENCYAPI_KEY="your_currencyapi_key_here"
Never commit your .env file to version control. It’s included in .gitignore by default.

​
Obtaining API keys

The Currency Converter API uses multiple providers for redundancy and accuracy. You need to obtain API keys from each provider.
  1. Visit https://fixer.io/
  2. Click “Get Free API Key” or “Sign Up”
  3. Complete the registration form
  4. Verify your email address
  5. Copy your API key from the dashboard
  6. Add it to your .env file as FIXERIO_API_KEY
Free tier includes:
  • 100 requests per month
  • Real-time exchange rates
  • 170+ currencies
  1. Visit https://openexchangerates.org/
  2. Click “Sign Up” in the top right
  3. Choose the “Free” plan
  4. Complete the registration
  5. Your App ID will be displayed on the dashboard
  6. Add it to your .env file as OPENEXCHANGE_APP_ID
Free tier includes:
  • 1,000 requests per month
  • Hourly updates
  • 200+ currencies
  1. Visit https://currencyapi.com/
  2. Click “Get Free API Key”
  3. Sign up with your email
  4. Verify your account
  5. Copy the API key from your dashboard
  6. Add it to your .env file as CURRENCYAPI_KEY
Free tier includes:
  • 300 requests per month
  • Real-time rates
  • 150+ currencies
While you can run the API with just one provider, using all three ensures maximum reliability and accuracy through rate averaging.

​
Docker setup

The Currency Converter API uses Docker Compose to orchestrate multiple services.
1

Review docker-compose.yml

The provided docker-compose.yml defines three services:
services:
  db:
    image: postgres:15
    container_name: currency-converter-db-compose
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:6
    container_name: currency-converter-redis-compose
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:
2

Start services

Launch all services with a single command:
docker-compose -f docker/docker-compose.yml up -d
This command:
  • Starts PostgreSQL on port 5432
  • Starts Redis on port 6379
  • Creates persistent volumes for data
  • Runs containers in detached mode
3

Verify services are running

Check that all containers are healthy:
docker-compose -f docker/docker-compose.yml ps
You should see both db and redis services with status “Up”.
4

View logs

Monitor service logs to ensure everything is working:
# All services
docker-compose -f docker/docker-compose.yml logs -f

# Specific service
docker-compose -f docker/docker-compose.yml logs -f db

​
Starting the API

Once your environment is configured and services are running, start the API server.

​
Using Docker

docker-compose -f docker/docker-compose.yml up --build

​
Using Poetry (local development)

If you prefer running locally without Docker: 
# Install dependencies
poetry install

# Start the server
poetry run uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

​
Verifying installation

1

Check API health

Visit the API documentation to confirm it’s running:
curl http://localhost:8000/docs
You should see the Swagger UI interface in your browser at http://localhost:8000/docs.
2

Test supported currencies endpoint

Verify that the API successfully initialized supported currencies:
curl http://localhost:8000/api/currencies
Expected response:
{
  "currencies": [
    "USD",
    "EUR",
    "GBP",
    "JPY",
    "AUD",
    "CAD",
    "CHF",
    "CNY",
    "SEK",
    "NZD"
  ]
}
3

Test a conversion

Make a test conversion request:
curl http://localhost:8000/api/convert/USD/EUR/100
You should receive a successful conversion response with the current exchange rate.
On first startup, the API fetches supported currencies from all providers and stores them in the database. This may take a few seconds.

​
Troubleshooting

If you see Connection refused errors:
  1. Verify PostgreSQL is running: 
    docker-compose -f docker/docker-compose.yml ps db
  2. Check the DATABASE_URL in your .env file
  3. Ensure the hostname matches your Docker service name (usually db when using Docker Compose)
  4. Verify credentials match between .env and docker-compose.yml
If Redis connections fail:
  1. Check Redis is running: 
    docker-compose -f docker/docker-compose.yml ps redis
  2. Verify REDIS_URL in your .env file
  3. Test Redis connection: 
    docker-compose -f docker/docker-compose.yml exec redis redis-cli ping
Expected response: PONG
If you see “Provider unavailable” errors:
  1. Verify your API keys are correct in the .env file
  2. Check you haven’t exceeded your free tier limits
  3. Test provider connectivity manually: 
    curl "http://data.fixer.io/api/latest?access_key=YOUR_KEY"
  4. Ensure at least one provider is working (the API can function with a single provider)
If ports 8000, 5432, or 6379 are already in use:
  1. Modify the port mappings in docker-compose.yml: 
    ports:
  - "5433:5432"  # Use 5433 on host instead
  2. Update your .env file to match the new ports
  3. Restart the services

​
Next steps

Now that your Currency Converter API is set up and running:

Build docs developers (and LLMs) love

Get started for freeTalk to us