MrMaz / rockets-starter

Rapid Enterprise Development Toolkit (Quick Start Project)

Rockets Starter

The starter project is a monorepo composed of an example Rockets API implementation with a compilimentary Rockets React web front end.

In this README you will find setup and installation instructions for many different environments, including VSCode Container, Docker, and local machine.

Project

Environment

Choose your preferred development environment from one of the three options below.

• VSCode Dev Container
• Docker Compose
• Local Machine

VSCode Dev Container

If you are familiar with VSCode, running the project in a dev container is highly recommended. It is an additional layer on top of Docker which enables you to edit the files on the container app directly from VSCode.

The underlying Docker configuration provides a Node server and a PostgreSQL server. Both servers are pre-configured, there is no additional setup required.

Prerequisites

• Visual Studio Code
• Remote Containers Extension
• Docker Desktop

Launch Container

1. From a new VSCode window, open the Source Control panel.
2. Click the Clone From Repository button.
3. Enter the project's git url: https://github.com/conceptadev/rockets-starter.git
4. Choose a local folder where the project will be cloned.
5. Once the project has loaded, you should see a notification in the lower right corner that a Dev Container configuration file has been detected.
6. Click the Re-open In Container button.

VSCode will automatically invoke Docker to build, compose, connect to the container, and install all dependencies. Depending on your machine and internet connection, this could take a while. Don't worry, it only needs to build the container the first time!

By default, and for performance reasons, the docker-compose.yml is configured to create a new Docker volume and check out a fresh copy of the repo there. These are NOT your local files, if you manually delete the volume, any modifications will be lost.

Open a new terminal window, and you should find yourself in the /workspace directory.

You are now connected to the container and ready to initialize and run the sandbox in the remote container!

Docker Compose

Running the project on Docker is a quick way to get the ideal environment created and configured. See also VSCode Dev Container which is an additional layer on top of Docker.

The Docker configuration provides a Node server and a PostgreSQL server. Both servers are pre-configured, there is no additional setup required.

Prerequisites

• Docker Desktop

Installation

Clone the source code into your local directory of choice, and run docker compose up.

git clone https://github.com/conceptadev/rockets-starter.git
cd rockets-starter
docker compose up

This will build the container, and install all dependencies. Depending on your machine and internet connection, this could take a while. Don't worry, it only needs to build the container the first time!

By default, and for performance reasons, the docker-compose.yml is configured to create a new Docker volume and check out a fresh copy of the repo there. These are NOT your local files, if you manually delete the volume, any modifications will be lost.

Connect to Container

1. Open Docker Desktop
2. Open the Containers / Apps menu.
3. Select the container app whose name includes rockets-starter.
4. Click the CLI button to connect to the running docker app's terminal.

Open a new terminal window, and you should find yourself in the /workspace directory.

You are now ready to initialize and run the sandbox in your Docker container!

Local Machine

Follow the steps below to set up the environment on your local machine.

Prerequisites

Your local environment must have the following prerequisites installed:

• Node >= v16.10.0
• PostgreSQL >= v11 (>= v12 recommended)
• Yarn >= 1.21.0 (latest v1.X recommended)

You can verify that you have these installed by running the following shell commands.

node --version
postgres --version
yarn --version

Installation

Clone the source code into your local directory of choice, and run yarn install.

git clone https://github.com/conceptadev/rockets-starter.git
cd rockets-starter
yarn install

Since we are working in a monorepo, you only need to run install from the root of the project.

Configuration

You may need to modify the database configuration depending on how your local PostgreSQL instance is set up.

The simplest way to change the connection settings is by exporting the DATABASE_URL env variable like the following example.

For both examples below, you will need to modify the the DATABASE_URL to match your environment.

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/rockets-starter

Or, you can create the packages/rockets-api/.env file containing a line like the following example.

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/rockets-starter

For more advanced configuration, you can edit the packages/rockets-api/src/ormconfig.ts file directly.

You are now ready to initialize and run the sandbox on your local machine!.

The Sandbox

Congratulations! You have your environment set up, and you are ready to start playing.

Initializing

Starting again from the root of the project, run this command to initialize the sandbox.

yarn sandbox:init

This will run all database migrations to create the schema, and run the database seeder to populate some data.

A Super Admin account will be created as follows:

Username: superadmin Password: Test1234

Start the API

To start the API, run this command:

yarn start:api

The api should now be running at http://localhost:3001

You can view the endpoint documentation and interact with the API in realtime at http://localhost:3001/api

Start the Web Server

To start the web server, run this command:

yarn start:web

The web should now be running at http://localhost:3000/login

Rebuilding the Sandbox

If you ever want to start over with a fresh database, run this command to rebuild the schema.

WARNING: this is a destructive operation!

yarn sandbox:rebuild

Contributing

This project is currently in alpha testing, however, feedback is highly appreciated and encouraged!

Pull requests will be gratefully accepted in the very near future, once we have finalized our Contributor License Agreement.