17th-Battalion-Tracker/README.md

17th Website Project

Basic Dev Environment

Assumes you have Docker and Docker Compose installed (included in Docker Desktop).

1. Copy /.env.example to /.env and populate with desired options.
2. Navigate to the project root in a terminal.
3. Run docker compose up -d --build db
4. Run docker compose up -d --build api
5. Let it build the images

You will have a SQL server accessible on port 12730 from your host (and publicly if not firewalled) for SQL Workbench access.

The API will launch and be accessible on port 3000 from your host via Postman or a browser.

Nginx (optional)

Adjust the listening ports

Adjust the listening ports in two places: /nginx/api.conf: Change the listening port in one or both servers /docker-compose.yaml: Change the 'ports' entries in the nginx service. The first part is the host port to bind, the second part is the container port to bind. For example, 9000:3440 would route inbound requests for localhost:9000 on to the nginx container (and the nginx service) at port 3440.

Adding Nginx without SSL

If you want to use Nginx without SSL, comment out the second server object in nginx/api.conf so you're only handling basic HTTP requests. Run docker compose up -d --built nginx.

Adding Nginx with SSL

You can use the commands in the other file of /nginx to generate self-signed certificates for the domain you're hosting this at. Certbot will remotely check routing for that domain to itself and assign a certificate if valid, based on the well known acme challenge already set up in the /nginx/api.conf file.

IMPORTANT: If you want to do this, you'll need to comment out the second server object in /nginx/api.conf FIRST so Nginx doesn't crash when it looks for not-yet-existing SSL certs, and can respond on port 9230 (or whatever you've set it to) with the response. Then launch, ensure Nginx is running, then launch a Certbot command to check the domain endpoint.

Services in Docker Compose

DB

MySQL database with relatively default configuration

• references .env file for SQL root password and other information
• exposes SQL interface on port 12730 of the host - inbound access still subject to firewall restrictions
• natively accessible at the unchanged 3306 port for any containers within the same Compose project's default bridge network -- i.e., the api service in this project references the mysql container by hostname 'db', matching the service name

API

Node.js-served API using express.js and Sequelize. Documentation in OpenAPI 3.0 spec.

• references DB connectivity details & shared secret for authenticating HTTP requests from .env file
• contains controllers, models, and routes
  • controllers
    • defines actions to be taken in response to incoming web requests
    • includes data processing, database actions, and response actions
  • models
    • defines entity models - entity default fields and constraints
  • routes
    • pairs API endpoints with controller definitions
  • junctionModels
    • a folder for modeling entities that serve explicitly as junction points -- most notably 'event' formats

db/index.js imports models and defines relations among them. it exports a 'db' object containing the Sequelize instance as well as all imported models. This is referenced in the primary application, as a database synchronization is performed at runtime.

/index.js Contains the main application logic and express configuration. It currently uses CORS and a very in-development section, but with basic authentication through standard bearer tokens. a JWT alternative is commented out.

This main logic also instructs Sequelize to sync the database on launch. force: true, all data will be wiped as tables are dropped to account for possible changes in the schema definitions. This is a development tool and should be disabled in production.

Nginx and Certbot

Optional nginx instance for serving the API via reverse proxy on an external port of your choosing. This include a certbot container for acquiring a self-signed certificate, and bind mounts can be changed to utilize them to secure the API with SSL.

17th-web

This is a Vue instance designed to interface with the API and display the information to users, as well as permit administrators to manipulate the database. This has fallen behind active API development and may no longer work. This can be replaced with AJ's demo site if favored.

Resources

• Bootstrap
• Vue 3 CRUD Tutorial
• Node.js & Sequelize (MySQL) Tutorial