How‐to: Local DEV deployment using docker

Overview

This quick-start guide details how to establish a local development (DEV) environment for the whereis-api-v0 project using Docker containers. Designed for developers using Mac and Linux with Docker already installed, this guide focuses on a fresh deployment, requiring minimal initial setup. It just works.

Quickstart

• Start the PostgreSQL container on port 5432.
• Create the whereis database and grant access to whereis_user.
• Start the Whereis API container on port 8037.
• Preload the database with two built‑in sample tracking numbers:
  • eg1-012301230123
  • eg1-123412341234

You'll have two healthy containers:

IMAGE                  STATUS             PORTS                    NAMES
local/whereis-api-v0   Up ... (healthy)   0.0.0.0:8037->8037/tcp   whereis-api-v0
postgres               Up ... (healthy)   0.0.0.0:5432->5432/tcp   pg-whereis

---

Step 1: Setup two containers

Get the code

git clone https://github.com/eagle1-sys/whereis-api-v0
cd whereis-api-v0

Generate configuration, build docker image, and start services

make whereis

Optional

make help

---

Step 2: Verify local deployment

Verify application health and database connection. Expect a 200 OK status.

curl -I http://localhost:8037/app-health

Test the status API with a built-in sample tracking ID.

curl http://localhost:8037/v0/status/eg1-012301230123

Test the Whereis API with an authorization header. Use test key eagle1 to ensure authenticated requests are handled.

curl http://localhost:8037/v0/whereis/eg1-012301230123 --header 'Authorization: Bearer eagle1'

Performance benchmark (optional)

Benchmark API performance using ApacheBench:

ab -n1000 -c200 localhost:8037/v0/status/eg1-012301230123

Example output on a Apple Macbook Air M5 (2 Core, 2GB for docker):

Requests per second:    4466.52 [#/sec] (mean)
Time per request:       44.778 [ms] (mean)
Time per request:       0.224 [ms] (mean, across all concurrent requests)
Transfer rate:          1613.88 [Kbytes/sec] received

---

Step 3: Post-deployment configuration

By default, we use SQLite as the local database. Very easy.

Configuration files

docker-compose.yaml (needs modification)
    - APP_PORT
    - APP_ENV
    - WHEREIS_API_KEY

source-api-keys.env (needs modification)
    - Logistics source API keys

Dockerfile (rarely modified)
    - APP_PORT

config.ts (do not modify)
    - Application default configuration

Optional, if using postgres as the database

Change the default database passwords (_CHANGEME_) for enhanced security.

1. Change database passwords

   Change whereis_user password, replacing the placeholder with your chosen password:

   docker exec -it whereis-postgres psql -U postgres -c "ALTER USER whereis_user WITH PASSWORD 'YOUR_DB_PASSWORD';"

   Change postgres superuser password, replacing the placeholder with your chosen password:

   docker exec -it whereis-postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'YOUR_POSTGRES_PASSWORD';"

2. Update config files

   Modify docker-compose.yaml to reflect these new POSTGRES_PASSWORD and DB_PASSWORD values.

3. Redeploy both containers

   make update

Configure API keys

There are two types of API keys:

1. SOURCE_API_KEY: Required to access the logistics sources, such as FedEx. You must obtain these keys directly from the sources. Edit the source-api-keys.env file to set e.g. FDX and SFEX API keys.

2. WHEREIS_API_KEY: These keys are used to access the your own Whereis API serivce. You can create any unique keys to use. By default, eagle1 is the demo key for accessing the two preloaded sample tracking numbers.

   To create a new whereis_api_key to retrieve real tracking numbers, replace the placeholder sk-WHEREISKEY.

   # System to generate a random key for you
   make api-key 
   
   # Set a specific key
   make api-key ARGS="--user=new --key=sk-WHEREISKEY"

   Modify docker-compose.yaml

   WHEREIS_API_KEY: sk-WHEREISKEY

After modification, redeploy the API:

make update

---

Testing

Built-in unit tests

make test

Access real tracking numbers as an example

curl http://localhost:8037/v0/whereis/fdx-123412341234 \
     --header 'Authorization: Bearer sk-MYSECRETEKEY'

That is it. Enjoy!