Skip to content

Commit

Permalink
Merge pull request #307 from amplication/docs/run-your-app-in-dev-env…
Browse files Browse the repository at this point in the history 
…-updates

Updating the Run Your Service on a Development Environment page
  • Loading branch information
@yuval-hazaz
yuval-hazaz authored Aug 15, 2023
2 parents 9e99d73 + 2a2baa7 commit 643e911
Showing 1 changed file with 67 additions and 52 deletions.
119 changes: 67 additions & 52 deletions docs/how-to/run-dev-env.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,40 @@
---
id: run-dev-env
title: How to run your service on development environment
sidebar_label: Run your services on development environment
title: How to Run Your Service on a Development Environment
sidebar_label: Run Your Services on a Development Environment
slug: /getting-started/dev-env
---

# Run Your Service on Development Environment
# Run Your Service on a Development Environment

To build and run your generated application in a local development environment follow this tutorial.
VS Code is used for demonstration in this article, but the process can be done on any IDE or directly in the command line with npm CLI.
It's possible to run the code that Amplication generates for your service locally on your machine.
This page will guide you through 7 steps to get your service working in a development environment.

## Summary
Let's get started.

In this article you will go through the following steps:
## Prerequisites

1. Get the application source code
2. Install packages from npm for the server
3. Start docker container for your database
4. Initialize your database
5. Run your server
6. Install packages from npm for the Admin UI
7. Run the Admin UI
Before proceeding with this guide, make sure that you have the following technologies installed:

:::important
Before you start make sure you have Node.js 14, npm, and Docker installed.
:::

## Step 1 - Get the application source code

First, get your application source code from Amplication.
- Node.js >= 14
- NPM >= 6.14.4
- Docker

The best way to do it is to sync your application with a GitHub repository by following [this guide](/sync-with-github).
:::info
Also, make sure your service is already connected to a git provider. To do that, please see the [Sync With GitHub](/sync-with-github/) or [Sync With Bitbucket](/sync-with-bitbucket/) page.
:::

Instead, if you prefer to download the source code as a ZIP file, follow these steps:
## Step 1 - Clone Your Service's Repo

1. Commit all your changes so Amplication generates the updated source code.
2. Click on the **Download Code** button on the latest commit. You'll get a ZIP file.
3. Extract the ZIP file to a local folder.
4. Open your application with your favorite IDE
First, visit the git repo that you're syncing your service to.
Clone the repo into a separate folder on your computer.

![](./assets/download-code.png)
- [Cloning a repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
- [Cloning a repository on Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/clone-a-git-repository/)

## Step 2 - Install packages from npm for the server
## Step 2 - Install Packages from NPM for the Server

Your application is using npm for package management. To install all the necessary package follow these steps:
Your application is using NPM for package management. To install all the necessary packages, follow these steps:

1. Open a command-line tool
2. Move to the **Server** folder
Expand All @@ -52,43 +43,65 @@ Your application is using npm for package management. To install all the necessa
cd server
```

3. Execute npm install or npm i to download and install all the packages
:::note
Depending on how you chose a **Monorepo** or **Polyrepo** style to push your code to your git repo, you will have to `cd` into an additional folder.
:::

For example, if your service is named `Order Service` and you chose a [_Monorepo_](/first-service/#step-4-select-your-repo-style) style, your server folder would be at `apps/order-service`.

If you chose the [_Polyrepo_](/first-service/#step-4-select-your-repo-style) style, there will be a folder named `order-service` at the root of your repo.
In that case, run `cd order-service`.

3. Execute `npm install` or `npm i` to download and install all the packages

```
npm install
```

![](./assets/npm-server-install.png)
:::caution
If you run into issues during the installation step, please see our troubleshooting guide on [installation fails](/errors/installation-fails/).
:::

## Step 3 - Start a Docker Container for Your Database

## Step 3 - Start docker container for your database
To start the database, you need to run a Docker container.
In the server folder of your service's generated code, you will find a `docker-compose.yml` file, which is used to define and run your application's services.

To start the database you need to run a docker container using the following command:
To start the database, you need to run a Docker container using the following command:

```
npm run docker:db
```

## Step 4 - Initialize your database
:::info
The `docker-compose.yml` file lets you to manage all your service's components in an isolated environment.
:::

## Step 4 - Initialize Your Database

Now you need to create your application schema on the database. To do so Amplication uses Prisma and the Prisma migrate command.
Now you need to create your application schema in the database. To do so, Amplication uses Prisma and the Prisma migrate command.

First, execute the following command in the command-line tool to generate the Prisma client

```
npm run prisma:generate
```

Now, execute the following command in the command-line tool to generate the schema on the database
:::caution
If Prisma is denied access to the PostgreSQL DB, please see [our troubleshooting guide](/errors/prisma-denied-access-on-postgres/) to fix that.
:::

Now, execute the following command in the command-line tool to generate the schema in the database

```
npm run db:init
```

:::tip
To view the full Prisma commands or any other script you can open the package.json file and look for the relevant command in the scripts section
To view the full Prisma commands or any other script, you can open the `package.json` file and look for the relevant command in the scripts section.
:::

## Step 5 - Run your server
## Step 5 - Run Your Server

That's it, your server is ready!
Execute the following command to start your server
Expand All @@ -97,27 +110,31 @@ Execute the following command to start your server
npm run start
```

By default, your server is now available at http://localhost:3000
By default, your server is now available at `http://localhost:3000`

Try to open one of these URLs and have fun
Open one of these URLs and have fun.

- http://localhost:3000/api
- http://localhost:3000/graphql
- [`http://localhost:3000/api`](http://localhost:3000/api)
- [`http://localhost:3000/graphql`](http://localhost:3000/graphql)

To read more about the technologies and structure of your server read [this article](../../getting-started)
To read more about the technologies and structure of your server, read [this article](../../getting-started).

## Step 6 - Install packages from npm for the Admin UI
## Step 6 - Install Packages from NPM for the Admin UI

Now that your server is ready, you can build and run the Admin UI - a React client with ready-made forms for creating and editing all the data models of your application.

To install all the packages needed for the client, follow these steps:

1. in the command-line tool, move to the Admin folder. In case you are still in the Server folder, execute this command
1. In the command-line tool, move to the Admin folder. If you are still in the Server folder, execute this command

```
cd ../admin-ui
```

:::note
Depending on the name of your service and your repo style, the name of the admin UI folder can be different.
:::

2. Execute `npm install` or `npm i` to download and install all the packages

```
Expand All @@ -126,16 +143,14 @@ npm install

## Step 7 - Run the Admin UI

To run the React application with the Admin UI execute the following command
To run the React application with the Admin UI, execute the following command

```
npm run start
```

By default, your client is now available at http://localhost:3001

![](../getting-started/assets/generated-app/admin-ui.png)
By default, your client is now available at `http://localhost:3001`

:::tip
Make sure that the server is started and running in the background when initiating the admin UI. You can run npm run start for the admin UI in a separated shell from the one running the server.
:::
Make sure that the server is started and running in the background _before_ starting the admin UI. You can run `npm run start` for the admin UI in a separate shell from the one running the server.
:::

0 comments on commit 643e911

Please sign in to comment.