Getting Started with Amplify

Prerequisites: Visual Studio Code, or some other IDE of your choice if running locally.

Github Codespaces

Codespaces is the simplest way to get up and running, and there are multiple ways to use Codespaces, depending on your wants and needs.

Local Codespaces

From the green Code <> tab on the main repository page, click Codespaces then the + button. Once a codespace appears, you can chose to Open in your local editor.

Once your editor opens, you should see something similar to this:

From this shell, you can check out or create a branch, or use the commands in package.json to get the app started. You can also inspect ports tab to see where the app or the development instance of PostgreSQL can be accessed.

This setup will work if don't want to install an editor as well. Just click open in browser and you will be directed to an instance of VsCode's web-based IDE, which will work mostly the same, but may be limited in some functionality.

Running a Containerized Environment with Docker on your local machine

You can use a container engine like Docker (which is what Codespaces is doing) to run Amplify on your local machine. This is a good option for long-term or frequent contributors because Codespaces will get rid of your environment after a while and you could lose work in progress. Running in containers will also free you from installing NodeJs or Postgres on your machine since those will be packages in the container image.

Prerequesites

You'll need Docker cli and docker-compose. The easiest way to install the cli is to use Docker Desktop or Rancher Desktop. Both are free for this scale of development. Docker Desktop has a better gui if you like that sort of workflow.

• Docker Desktop
• Rancher Desktop
• Lima Wildcard choice if you don't want a gui at all

No matter which you choose, you will most likely have to install docker-compose separately.

• docker-compose installation

Starting Amplify

Once docker and docker-compose are installed, you should be able to run the app and postgres by using:

./script/start.sh

Before running that command, you may have to make the script executable, depending on your environment.

• On Ubuntu: chmod a+x ./script/start.sh ./script/stop.sh

Once you've run start.sh and the containers are finished being built, you should see your terminal prompt change to something like

/src/amplify #

If you see this, you've successfully entered the container and can navigate the app like it's on your local machine. To exit, type

exit

At first start-up, you will have to create a database and run migrations. Postgresql is already running in a separate container, so setting up the database will be as easy as running

npm run db:create

There is some seed data that will be added to the database to get you up and running. Database data will persist in a volume between container restarts.

Finally, to start the app, try either

npm run dev

- OR -

npm run dev:backend

When you change code in the repository on your local machine, it will automatically get copied and trigger hot reloading inside the container.