Skip to content

Commit

Permalink
1112 improve documentation and setup process (#255)
Browse files Browse the repository at this point in the history
* chore(api): update docker configuration

* chore(infra): update readme and remove duplicate docker compose

* chore(infra): expose 3001 from interface, and update docs

* fix(api): add sqllite back to dockerfile

* chore(docs): add CERAMIC_CACHE_SCORER_ID instructions

* chore(docs): env file clarification and interface instructions

* chore(docs): clarify docker compose instructions

* Separated instructions for w/ docker & w/o docker

* Adding run verifier step

* Added step to clone the repo

* Updated the name of the interface example env file

* Specify directory for docker setup

* updating order for w/o docker setup

* fix(infra): revert update to Dockerfile

* feat(infra): expose postgres port

---------

Co-authored-by: michaelgreen06 <michaelgreen06@gmail.com>
  • Loading branch information
Tim Schultz and michaelgreen06 authored Jun 2, 2023
1 parent 2b74bcc commit 683784a
Show file tree
Hide file tree
Showing 4 changed files with 83 additions and 54 deletions.
100 changes: 77 additions & 23 deletions SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,57 +14,92 @@ the main two for you to set up:
└── test/ # End-to-end tests
```

## API
## Setting up With Docker
A [`Docker Compose`](./docker-compose.yml) file has been provided to quickly get the API, database, verifier, celery workers, and interface
up and running. Setup instructions are provided below:

A [`Dockerfile`](./api/Dockerfile) has been provided to quickly get the API
environment up and running. Setup instructions are also provided below.
1. Download the Passport Scorer Repo

### With Docker
```shell
git clone https://github.com/gitcoinco/passport-scorer.git
```

1. Create a new `.env` file by copying the existing `.env-sample` file
2. Create a new `.env` file in the `api` directory & update the variables.

```shell
# From inside the api/ directory
cp .env-sample .env
```
Update the `DATABASE_URL` variable to `postgres://passport_scorer:passport_scorer_pwd@postgres:5432/passport_scorer`

Update the `CERAMIC_CACHE_SCORER_ID` variable to match a `SCORER_ID` you create from the scorer UI.
(You will have to complete all these setup steps first, then you will be able to create a `SCORER_ID` from the UI & update this variable.)

2. Run and build the `Dockerfile`. The first time you run this, it will take
3. Create a new `.env` file in the `interface` directory & update the varaibles.
```shell
# From inside the interface/ directory
cp .env.example .env
```
Update the `NEXT_PUBLIC_PASSPORT_SCORER_ALCHEMY_API_KEY` varaible to an Alchemy API key you own. If you don't have one, you can create one for free [here](https://docs.alchemy.com/reference/api-overview)


4. Run and build the `Dockerfile` from the root directory. The first time you run this, it will take
a while to build the Docker images.

```
cd api
docker-compose up --build
```
Upon subsequent runs, you can omit the `--build` flag.

5. Perform a database migration in the root directory by opening a new terminal & running:

```shell
docker-compose exec api python manage.py migrate
```

The API will be running on port 8002, interface on 3001, redis on 6379, and the database will be running on port 5432.

The API will be running on port 8000 and the database will be running on port
5432.

### Without docker

## Setting up Without docker

We assume that you have a working python environment set up on your machine with
the following:

- A recent version of Python
- `pipenv`

### Download this Repo

```shell
git clone https://github.com/gitcoinco/passport-scorer.git
```

### API

The following commands should be run from within the `api/` directory.

1. Activate your local virtual environment:
1. Create a `.env` file:

```shell
cp .env-sample .env
```

2. Activate your local virtual environment:

```
pipenv shell
```

2. Install dependencies in your virtual environment:
3. Install dependencies in your virtual environment:

```
pipenv install
pipenv install --dev
```

3. Start the dev server:

**First**: make sure you have the `.env` file in the api folder, with proper
values (copy the `.env-sample` and adjust it). Then:
4. Start the dev server:

```shell
gunicorn -b 127.0.0.1:8002 -w 4 -k uvicorn.workers.UvicornWorker scorer.asgi:application
Expand All @@ -76,27 +111,47 @@ or:
uvicorn scorer.asgi:application --reload --port 8002
```

Start the celery worker:
5. Run Redis locally in a new terminal:

```shell
pipenv shell
docker run -d -p 6379:6379 redis
```

> Make sure you have Docker running
6. Start the celery worker:

```shell
celery -A scorer worker -l DEBUG
```

And run Redis locally:
### Migrations

You will need to run database migrations in the `api/` directory by running:

```shell
docker run -d -p 6379:6379 redis
pipenv shell
python manage.py migrate
```

> Make sure you have Docker running
### Verifier

## Interface
Navigate to the `verifier/` directory & run the verifier:
```shell
yarn
#yarn only needs to be run when first installing the app
yarn dev
```

### Interface

The front end is built using Next.js and is using a fairly standard installation
without much customization.

To run the front end, change into the `interface/` directory and install the
dependencies:

```
yarn
```
Expand All @@ -107,7 +162,7 @@ Copy the `.env.example` file:
cp .env.example .env
```

You will need an [Alchemy API key](https://docs.alchemy.com/reference/api-overview).
Update the `NEXT_PUBLIC_PASSPORT_SCORER_ALCHEMY_API_KEY` varaible to an Alchemy API key you own. If you don't have one, you can create one for free [here](https://docs.alchemy.com/reference/api-overview)

To start the development server:

Expand All @@ -119,8 +174,7 @@ yarn dev

### API

> The following assumes you are in the api/ directory and that you've already
activated your local virtual environment
> The following assumes you are in the api/ directory and that you've already activated your local virtual environment
In the `./api` directory run (make sure your local virtual env is activated):

Expand Down
28 changes: 0 additions & 28 deletions api/docker-compose.yml

This file was deleted.

5 changes: 4 additions & 1 deletion docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ services:
build: interface

ports:
- "127.0.0.1:3001:3000"
- "3001:3001"

verifier:
build: verifier
Expand All @@ -53,3 +53,6 @@ services:

volumes:
- ./postgres_db_data:/db_data

ports:
- 5432:5432
4 changes: 2 additions & 2 deletions interface/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ COPY . .
# Build the Next.js app
RUN yarn build

# Expose port 3000 to the outside world
EXPOSE 3000
# Expose port 3001 to the outside world
EXPOSE 3001

# Set the command to start the app
CMD [ "yarn", "start" ]

0 comments on commit 683784a

Please sign in to comment.