The Stack

Table of Contents

• Overview
• Getting Started
  • Prerequisites
  • Installation
  • Environment Configuration
    • App Pepper
    • AuthJS Secret
    • Env variables
  • Running the Application
• Production build
  • Create the production image
  • Run the production image
  • Useful Commands
• Features
• Version Control and Maintenance
• Roadmap
• License

Overview

The Stack is a web application developed using Next.js. It serves as a recruitment task, allowing users to interact with a server explorer interface. This app displays a list of servers along with their distance from the user, and users can sort this list by name or distance. The flag of the country to which the server belongs accompanies it.

Please note that the current solution differs from the one initially provided in the technical task. In the original version, my task involved requesting specified authentication and server list retrieval endpoints. The current solution simulates similar behavior using Drizzle ORM, SQLite, and Argon2, representing a shift in the implementation approach.

Solution available at URL https://developer-app-rana.fly.dev

Getting Started

Prerequisites

To install this project, you will need to have the following on your machine :

We recommend to use the node version specified in the .nvmrc file.

Installation

Run the following commands :

 # Install dependencies and Husky hooks
npm install

Environment Configuration

App Pepper

The "pepper" is a secret added to the hashing process to provide an additional layer of security. It's similar to salt, but while salt is typically stored alongside the hashed password in the database and is unique for each user, pepper is a secret value that is kept separate from the database and is the same across all users.

The purpose of a pepper is to defend against attacks where the attacker has gained access to the hashed passwords and the salts but not the application code or configuration where the pepper is stored. In such a case, the attacker would not be able to crack the passwords using a rainbow table or similar precomputed table attack because they would not have the pepper value that was used in the hashing process.

To generate an arbitrary string, you can use the following command in the terminal:

openssl rand -base64 32

AuthJS Secret

An AuthJS secret is a random string used to hash tokens, sign cookies, and generate cryptographic keys. To generate an arbitrary string, you can use the following command in the terminal:

openssl rand -base64 32

Or generate one online

Env variables

Create a .env file with the following variables:

• NEXT_PUBLIC_HOST: The host URL.
• DB_PATH: A path where the database file will be stored
• APP_PEPPER: The secret key used as a "pepper" in the password hashing process.
• NEXTAUTH_SECRET: The secret key for NextAuth. Paste here AuthJS Secret.
• NEXTAUTH_URL: Same as NEXT_PUBLIC_HOST.
• E2E_TEST_USERNAME: Username for E2E testing.
• E2E_TEST_PASSWORD: Password for the E2E test user.

Running the Application

To run the app in dev mode, run the following commands in the terminal:

# Create the database
npm run db:migration:run

# Seed the data base
npm run db:seed

# Create application user
npm run db:user:create

# Run the app in dev mode
npm run dev

Production build

The app contains everything needed to get all Next.js production environments up and running with Docker Compose.

Combined with the Next Output Standalone feature, only node_modules files required for production are copied into the final Docker image.

First, build the production server (Final image approximately 110 MB).

Create the production image

# Create a network that allows containers to communicate
# with each other by using their container name as a hostname
docker network create the_stack_network

# Build prod
docker compose -f docker-compose.prod.yml build

Run the production image

To run the app in production mode, run the following command in the terminal:

# Up prod in detached mode
docker compose -f docker-compose.prod.yml up -d

Open http://localhost:3000.

Useful commands

# Stop all running containers
docker kill $(docker ps -aq) && docker rm $(docker ps -aq)

# Free space
docker system prune -af --volumes

Features

• Built with Next.js, Drizzle ORM and SQLite.
• Utilize @node-rs/argon2 to hash and verify passwords, providing a high level of security for user data.
• Responsive Web Design (RWD).
• Unit, Integration, and E2E Testing with Vitest and Playwright.
• SVG sprites for icons.
• Static code linting and formatting using Eslint and Prettier,
• Continuous Integration and Deployment with GitHub Actions running lint, vitest, playwright, and deploy commands.
• Deployment automated on Fly.io.
• Semantic versioning with semantic-release.
• Automatic dependency updates with Renovate.
• Adherence to Conventional Commits standards.
• Use of lint-staged for code quality.
• Incorporation of Class Variance Authority (CVA) and TypeScript reset utility (ts-reset) for better type safety and cleaner code.

Version Control and Maintenance

This project uses semantic-release for version management, ensuring automated versioning and changelog generation. Before committing, we provide code quality by using lint-staged and following the Conventional Commits standard for commit messages. Renovate helps in keeping dependencies up-to-date.

Roadmap

Here is a list of upcoming functionalities and improvements:

• Integration with Microsoft Clarity.
• Integration with New Relic.
• Integration with Sentry.
• I18n support using (next-intl).
• MFA support.
• Passwordless login using GitHub, Apple, and Microsoft providers.
• Magic link authentication.
• Password reset functionality.
• Dark theme.
• Lazy loading mechanism for server list.
• Improve app colors for accessibility.
• Integration tests and enhanced coverage

License

The Stack App is software licensed under the MIT license.