How‐to: Local DEV deployment using docker

Overview

Welcome to the whereis-api-v0 project! This quick-start guide is your fast track to setting up a local development (DEV) environment using Docker containers. Designed for Mac and Linux folks who already have Docker installed, this guide is all about a fresh, frictionless deployment. Less setup, more coding. It just works!

Quickstart

• By default, we keep things super simple with SQLite as the local database.
• We'll start the Whereis API container on port 8037.
• To make life easier, the database comes preloaded with two built‑in sample tracking numbers:
  • eg1-012301230123
  • eg1-123412341234

When the dust settles, you'll have one happy, healthy container:

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

---

Step 1: Fire Up Your Environment

Grab the code

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

Generate configs, build the image, and start the engine

make whereis

Curious about what else you can do?

make help

---

Step 2: Kick the Tires (Verify Deployment)

Let's make sure the application is healthy and talking to the database. You should expect a friendly 200 OK status.

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

Test the status API using one of our built-in sample tracking IDs:

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

Test the Whereis API with an authorization header. Use our handy test key eagle1 to make sure authenticated requests are working smoothly:

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

Need for Speed? (Optional Benchmark)

Want to see how fast it goes? Benchmark the API performance using ApacheBench:

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

Example output on an 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: Tweak the Settings (Post-deployment)

The Configuration Files

Here's a quick cheat sheet for what files do what:

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

---

The Keys to the Castle (API Keys)

There are two types of API keys you'll need to know about:

1. SOURCE_API_KEY: These are the keys required to fetch data from logistics sources (like FedEx). You'll need to grab these directly from the providers. Pop open the source-api-keys.env file to set your FDX and SFEX API keys.

2. WHEREIS_API_KEY: These keys guard your own Whereis API service. You can create any unique keys you like! By default, eagle1 acts as a demo key for checking those two preloaded sample tracking numbers.

   Want to create a new WHEREIS_API_KEY to retrieve real tracking numbers? Replace the placeholder sk-WHEREISKEY below:

   # Let the system generate a random key for you
   make api-key 
   
   # Or, set a specific key yourself
   make api-key ARGS="--user=new --key=sk-WHEREISKEY"

   Then, update your docker-compose.yaml:

   WHEREIS_API_KEY: sk-WHEREISKEY

Whenever you tweak these settings, give the API a quick redeploy:

make update

---

Testing Time

Run the built-in unit tests to ensure everything is humming along perfectly:

make test

Try accessing a real tracking number

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

And that's a wrap! Enjoy your shiny new API.

---

Feeling Adventurous? Use Postgres

If SQLite isn't enough for you, you can easily swap over to Postgres.

make whereis DB_TYPE=postgres

Make sure to change the default database passwords (_CHANGEME_) to keep things secure!

1. Change those passwords!

   Update the whereis_user password (replace YOUR_DB_PASSWORD with a real password):

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

   Update the postgres superuser password (replace YOUR_POSTGRES_PASSWORD with a real password):

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

2. Update your config files

   Modify docker-compose.yaml so the POSTGRES_PASSWORD and DB_PASSWORD values match what you just set.

3. Redeploy both containers

   make update DB_TYPE=postgres