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.
Choose your preferred development environment from one of the three options below.
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.
- From a new VSCode window, open the Source Control panel.
- Click the Clone From Repository button.
- Enter the project's git url: https://github.com/conceptadev/rockets-starter.git
- Choose a local folder where the project will be cloned.
- Once the project has loaded, you should see a notification in the lower right corner that a Dev Container configuration file has been detected.
- 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.ymlis 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!
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.
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 upThis 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.ymlis 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 Docker Desktop
- Open the Containers / Apps menu.
- Select the container app whose name includes rockets-starter.
- 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!
Follow the steps below to set up the environment on your local machine.
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 --versionClone 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 installSince we are working in a monorepo, you only need to run install from the root of the project.
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_URLto match your environment.
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/rockets-starterOr, you can create the packages/rockets-api/.env file containing a line like the following example.
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/rockets-starterFor 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!.
Congratulations! You have your environment set up, and you are ready to start playing.
Starting again from the root of the project, run this command to initialize the sandbox.
yarn sandbox:initThis 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
If you get an ECONNREFUSED error in this step, change the rockets-starter-ppostgres config on the docker-compose.yml with the following:
rockets-starter-postgres:
image: postgres
ports:
- 5432:5432
environment:
POSTGRES_DB: rockets-starter
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
To start the API, run this command:
yarn start:apiThe 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
If you get an EADDRINUSE error in this step, go to Docker Desktop, click Containers and search for the rockets-starter app. In the app's containers list, stop the rockets-starter-rockets-starter-1 instance. You should be able to run the API start command now.
To start the web server, run this command:
yarn start:webThe web should now be running at http://localhost:3000/login
If you get Unknown workspace "rockets-web" in this step, run the yarn dev command inside the packages/rockets-next-web folder.
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:rebuildThis 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.