/ˈɡaɡəl/

noun

1. a flock of geese.
2. the docker compose file bringing together produce goose's backend and frontend repositories.

Make sure you have docker and docker-compose installed and the Docker application is running before you attempt to execute any commands that start with docker-compose.

After cloning the repository we need to initialize the submodules:

git clone [email protected]:SJSUProduceGoose/gaggle.git
cd gaggle
git submodule init
git submodule update

Copy the .env.example file to .env and fill in the values.

cp .env.example .env

BYOK: Bring Your Own Key

Stripe is used to process payments. You will need to create an account and generate a private key and signing key. You can find more information here.

1. Register here and set up a Test account. There is no need to set up a live account at this time.
2. Go to the Stripe dashboard and click on Developers -> API keys.
3. Copy the Secret key and paste them in the .env file.
4. Set up the tax rates for your business. You can do so by going to the Stripe Tax Rates Dashboard.
   • To simplify things, you can set up automatic taxes and Stripe will automatically calculate the tax rate based on the address of the customer.
   • Configure the "origin address" to somewhere in the same state as your business.
   • And set the default product tax category to "Food for Immediate Consumption".

The private key is used to connect to the Stripe API. You can find this key in the Stripe dashboard under Developers > API Keys.

The signing key is used to validate webhooks from Stripe and protect against replay attacks.

To find your signing key execute the following command:

# don't forget to replace the key with your own
docker-compose run stripe-cli listen --api-key=$STRIPE_PRIVATE_KEY --print-secret

Make sure to update the .env with this new value.

If you are publishing the project to a public facing server, you can set up the webhook on Stripe and find the signing key under Developers > Webhooks.

You'll want to direct to /api/webhook/stripe/ and only need to select the checkout.session.completed event.

The positionstack API is used to resolve addresses to coordinates. You can find your API key in the positionstack dashboard. You'll need to create your own account and use the free plan.

If you have any issues starting the cluster, please refer to the troubleshooting section.

docker-compose up

NOTE: This step requires the backend container to be running with docker compose.

If you run into errors, see the Connecting to the Database section.

To build the necessary tables we can run the following command:

docker-compose exec backend python manage db build

To seed the database with some initial dummy data we can run the following command:

docker-compose exec backend python manage db populate

In the future if you ever need to reset the database you can run the following command:

# -d drop all tables before building
# -p repopulate the database with dummy data after building
docker-compose exec backend python manage db build -dp

NOTE: This step requires the backend container to be running with docker compose.

To create all the necessary the Stripe objects we need to run the following command:

docker-compose exec backend python manage stripe setup

Once you have initiated the database and Stripe objects you'll need to restart the backend:

docker-compose restart backend

If you encounter errors connecting to the database, especially in the Configuring The Database stage, the following instructions should fix things:

1. Stop the docker compose process, either by pressing Ctrl+C or by running docker-compose down if you launched the stack in detached mode (docker-compose up -d).
2. Delete the /postgres folder in the root of the project. Either by running rm -rf postgres or by deleting the folder in your Finder/file explorer.
3. Run docker-compose down once more
4. Run docker-compose up to start the stack again.

If you get errors from docker saying that a port is already in use, make sure there are no other docker containers or processes running on ports 3000, 5432, 8080, or 8000.

Once you've ensured that there are no other processes or containers running on those ports, then retry docker-compose up.

When checking out, you can use the following credit cards to test the payment flow:

If you make changes to the contents of the frontend or backend folders, or pull new changes, you'll need to rebuild the docker containers in which changes occurred.

To rebuild the frontend container, run the following command:

docker-compose build frontend

To rebuild the backend container, run the following command:

docker-compose build backend

After rebuilding you'll need to restart all the docker containers:

docker-compose down
docker-compose up

If there are new changes upstream, you pull the changes with:

git pull
git submodule foreach git checkout main
git submodule foreach git pull

And then follow the Rebuilding Containers instructions to rebuild the modified repository containers.

The hybrid mode is the recommended way to develop the frontend and backend. Due to performance restrictions, developing with a dockerized Nuxt container was found to be quite slow.

Hybrid mode will spin up the postgres, stripe-cli, nginx, and backend (complete with hot reloading) containers. And allow you to run the frontend locally on port 3000.

To start the hybrid mode, run the following command:

docker-compose -f docker-compose.yml -f docker-compose.hybrid.yml up

Make sure the .env file in your frontend folder is configured as follows:

NUXT_BASE_URL=https://localhost:8080/api
NUXT_PUBLIC_BASE_URL=https://localhost:8080/api

If you want to run the entire development context in docker, you can do so by running the following command:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

The only caveat is that the frontend will feel considerably slower tha the hybrid alternative, and you'll often have to reload the page as the hot reloading is a little hit-and-miss.

Good luck,

May the Goose be with you.