Setting Up the App with Docker

This guide walks you through setting up the full stack boiler-plate application using Docker. It's designed to get your local development environment up and running smoothly.

Pre-requisites

• Docker: Ensure Docker is installed on your machine. For installation instructions, visit the official Docker documentation.
• Docker Compose: This setup requires docker-compose. Verify it's installed by running docker-compose --version in your terminal. If you need to install it, follow the Docker Compose installation guide.

Working software versions

• Node @ 21.6.1
• Npm @ 10.2.4
• Docker @ 25.0.2

Step-by-Step Guide

1. Install Docker: If you haven't already, install Docker for your operating system and run the Docker application.

2. Prepare Environment Files:

   • Create a directory structure env/docker/local in the root of the project.
   • Within this directory, create api.env, web.env, and db.env files.
   • Populate these files with the environment variables listed below. For variables enclosed in [], replace them with your values. Other variables should remain as they are.

3. Build and Run Containers:

   • Open your terminal and navigate to the project directory.
   • Run docker-compose up --build to build images and run containers for the first time. This command also starts the services.
   • For subsequent starts, you can use docker-compose up to start the services without rebuilding the images.

4. Verify Setup:

   • After starting the services, ensure all containers are running correctly by executing docker-compose ps. Each service should be listed as "Up".
   • To verify the application is running as expected, navigate to http://localhost:3000 in your web browser (this port has been configured for you in the docker-compose file).

---

Environment Variables

Setting up your local docker environment requires specific environment variables. These variables configure the services and ensure they can communicate with each other.

Creating Local Docker Environment Files

In the project root, ensure the following structure exists: env/docker/local. Here's how to set up each .env file:

• WWW Environment (www.env):

  Note: Currently no env variables are needed for www -- but, you will need to create an empty www.env i.e. env/docker/local/www.env file for docker-compose to find.

• API Environment (api.env):

  NODE_ENV=development
  DB_HOST=db
  DB_PORT=5432
  DB_USERNAME=postgres
  DB_PASSWORD=[YourDatabasePassword] # Replace with your password
  DB_DATABASE=boilerplate_db
  JWT_ACCESS_SECRET=[YourJWTAccessSecret] # Replace with your JWT access secret
  JWT_REFRESH_SECRET=[YourJWTRefreshSecret] # Replace with your JWT refresh secret
  API_PORT=8081
  PAYMENT_SERVICE=stripe
  
  STRIPE_API_KEY=[YourStripeApiKey]
  STRIPE_WEBHOOK_SECRET=[YourStripeWebhookSecretKey]
  STRIPE_API_VERSION=2023-10-16
  STRIPE_SUCCESS_URL=http://localhost:3000/user/billing
  STRIPE_CANCEL_URL=http://localhost:3000
  STRIPE_YEARLY_SUBSCRIPTION_PRICE_ID=[YourStripeYearlyPriceId]
  STRIPE_MONTHLY_SUBSCRIPTION_PRICE_ID=[YourStripeMonthlyPriceId]
  STRIPE_OTP_FULL_PRICE=[YourStripeOneTimePaymentFullPriceId]
  STRIPE_OTP_DISCOUNT_PRICE=[YourStripeOneTimePaymentDiscountPriceId]
  

  Note:

  • The JWT_ACCESS_SECRET and JWT_REFRESH_SECRET are crucial for authentication. Ensure these are secure and unique values.
  • To test the Stripe webhook locally you can use Stripe's CLI and trigger the hook by entering stripe listen --forward-to localhost:8081/payments/stripe/webhook into your terminal. To setup Stripe's CLI you can follow this guide: https://docs.stripe.com/stripe-cli

• Database Environment (db.env):

  POSTGRES_USER=postgres
  POSTGRES_PASSWORD=[YourDatabasePassword] # Replace with your password
  POSTGRES_DB=boilerplate_db
  

  Note: The POSTGRES_PASSWORD should match the DB_PASSWORD in api.env.

• Web Environment (web.env):

  NEXT_PUBLIC_API_BASE_URL=http://localhost:8081
  NEXT_PUBLIC_API_BASE_URL_DOCKER_SERVICE=http://api:8081
  NEXT_PUBLIC_WEB_BASE_URL=http://localhost:3000
  NEXTAUTH_SECRET=[YourNextAuthSecret] # Replace with your NextAuth secret
  NEXTAUTH_URL=http://localhost:3000
  

  Note: NEXTAUTH_SECRET should be a secure, unique value used for encrypting session tokens.

---

Running Migrations and Seeds locally in dev

This section covers how to run database migrations and seeds within your Dockerized application environment. It's essential for setting up, updating, or resetting your database schema and initial data.

Migrations

To manage your database schema and ensure it's up to date with your application's models, you'll frequently need to run migrations. Here's how to execute migration commands within your Docker container:

1. Generating a New Migration

   If you've made changes to your entities and need to generate a migration file based on those changes, use the following command:

   docker exec -it container_name npm run migration:generate --name=MigrationName

2. Running Migrations

   Apply your migrations to update the database schema with:

   docker exec -it container_name npm run migration:run

3. Reverting the Last Migration

   To undo the last migration, use:

   docker exec -it container_name npm run migration:revert

Seeds

Seeding your database is crucial for populating it with initial data. To run your seed scripts within Docker, use the following command:

  docker exec -it [api_container_name] npm run seed

Note: Ensure you replace container_name with the actual name of your Docker container. This name can be found by running docker ps after your containers are up and running.

---

Running Migrations production

1. Create the migration locally
2. Re-build the docker image for /api and deploy to Dokku
3. Inside your Dokku server find the container where /api has been deployed too and enter it e.g. docker exec -it CONTAINER_ID sh
4. Then run the production migration script with dokku run DOKKU_APP_NAME npm run migration:run:prod

Note: Ensure you've synced your production database with your app in production

Common Issues and Troubleshooting

• Docker not starting: Ensure Docker is correctly installed and running. Restarting Docker can often resolve issues.
• Environment variables not recognized: Double-check the file paths and names. Ensure the env/docker/local directory structure is correctly created in the root of the project.
• Port conflicts: If you encounter errors related to ports being in use, check for other services running on the same ports and either stop those services or configure different ports in the .env files.

Security Considerations

Keep your secrets secure. Avoid committing .env files with sensitive information to version control. This project already has a .gitignore in the root so all you need to do is initialise git.

---