Skip to content

Commit

Permalink
docs: update readme (#138)
Browse files Browse the repository at this point in the history 
* docs: update readme

* docs: update based on Linda's (@lpatmo) feedback
  • Loading branch information
@tgrrr
tgrrr committed Apr 30, 2020
1 parent f83c2d0 commit 31ca929
Showing 1 changed file with 137 additions and 72 deletions.
209 changes: 137 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,88 +3,138 @@
![Test](https://github.com/codebuddies/django-concept/workflows/Test/badge.svg)
[![codecov](https://codecov.io/gh/codebuddies/backend/branch/master/graph/badge.svg)](https://codecov.io/gh/codebuddies/backend)

**Note:** This project is currently _in development_

## Features

- **Auto-reload** - modify the application code in your editor of choice. As you save changes, the application should reload automatically. There should be no need to restart containers to see code changes.
<!-- TODO -->

Background: https://github.com/codebuddies/codebuddies/issues/1136
## Reference

The API spec all the proof-of-concepts: https://app.swaggerhub.com/apis-docs/billglover/CodeBuddies/0.0.1
- [Background]
- [The API spec all the proof-of-concept]
- [Crowdsourced brainstorm of problems we want to solve]
- Will interact as the API supporting [https://github.com/codebuddies/frontend]

Crowdsourced brainstorm of problems we want to solve: https://pad.riseup.net/p/BecKdThFsevRmmG_tqFa-keep
## Getting started

## Setup

Although it is possible to run this locally, we recommend you run CodeBuddies locally using Docker. We assume you have Docker installed, but if not head on over to the Docker [Getting Started](https://www.docker.com/products/docker-desktop) guide and install Docker for your operating system.
We recommend you run CodeBuddies locally using Docker. We assume you have Docker installed, but if not head on over to the Docker [Getting Started] guide and install Docker for your operating system.

These instructions have been used on the following operating systems.

* Linux
* Mac OS
* Windows 10 Pro

Please note that Windows 10 Home is not supported by Docker Desktop at this time.
- Linux
- Mac OS
- Windows 10 Pro - Please note that Windows 10 Home is not supported by Docker Desktop at this time.

1. Fork this repository. This creates a copy of the repository for you to work on. For more help see this GitHub guide: [Fork a repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo).
2. Clone your fork. This creates a copy on your local computer. For more help see this GitHub guide: [Cloning a repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository).
1. Fork this repository. This creates a copy of the repository for you to work on. For more help see this GitHub guide: [Fork a repo].
2. Clone your fork. This creates a copy on your local computer. For more help see this GitHub guide: [Cloning a repository].

```plain
git clone git@github.com:codebuddies/django-concept.git cb
```bash
$ git clone https://github.com/codebuddies/backend codebuddies-backend
```

3. Navigate into the project directory.

```plain
cd cb
```bash
$ cd codebuddies-backend
```

4. Start the local development environment.

```plain
docker-compose up -d
```bash
$ docker-compose up -d
```

**Note:** `-d` starts Docker in detatched mode. See [logs](#debugging-with-docker-logs)

### Local development environment details

This will run the following components:

- Nginx, a web server: http://localhost:8000
- Adminer, a DB front-end: http://localhost:8001
- Nginx, a web server: http://localhost:8000 - view the application or make API calls
- Mailhog, a dummy mailbox: http://localhost:8025
- A PostgreSQL database
- The Django web application
- Adminer, a DB front-end: http://localhost:8001
- A PostgreSQL database `postgres://babyyoda:mysecretpassword@localhost:5432/codebuddies`

You can access the database through the Adminer front-end or using a local PostgreSQL client

You can view the application or make API calls by using the Nginx URL.
![screenshot of Adminer](https://i.imgur.com/Dtg5Yel.png =250x)

You can access the database through the Adminer front-end or using a local PostgreSQL client and the following URL: `postgres://babyyoda:mysecretpassword@localhost:5432/codebuddies`.
5. Create a superuser so that you can log into `http://localhost:8000/admin` by running the following in your terminal:

![screenshot of Adminer](https://i.imgur.com/Dtg5Yel.png)
```bash
$ docker-compose run --rm app ./manage.py createsuperuser
```

To stop the application and remove all containers, run the following.
6. You can populate the database with some random test data for development purposes by running

```plain
docker-compose down
```bash
$ docker-compose run --rm app ./manage.py init_data
```

5. Create a superuser so that you can log into http://localhost:8000/admin by running the following in your terminal: `$ docker-compose run --rm app ./manage.py createsuperuser`
All user accounts created by this command have the password `codebuddies`.

See the `init_data --help` command for more information:

```bash
$ docker-compose run --rm app ./manage.py init_data --help

usage: manage.py init_data [-h] [--clear-db] [--num-users NUM-USERS]
[--num-tags NUM-TAGS]
[--num-resources NUM-RESOURCES] [--version]
[-v {0,1,2,3}] [--settings SETTINGS]
[--pythonpath PYTHONPATH] [--traceback]
[--no-color] [--force-color]

Initialize the DB with some random fake data for testing and development

optional arguments:
--clear-db Clear existing data from the DB before creating test
data
--num-users NUM-USERS
Number of `User` objects to create (default 10)
--num-tags NUM-TAGS Number of `Tag` objects to create (default 10)
--num-resources NUM-RESOURCES
Number of `Resource` objects to create (default 10)
-v {0,1,2,3}, --verbosity {0,1,2,3}
Verbosity level; 0=minimal output, 1=normal output,
2=verbose output, 3=very verbose output
```

[See PR 127]


6. You can populate the database with some random test data for development purposes by running `$ docker-compose run --rm app ./manage.py init_data`. All user accounts created by this command have the password `codebuddies`.
---

## Editing Code
To stop the application and remove all containers, run the following:

With the local environment running, you can modify the application code in your editor of choice. As you save changes, the application should reload automatically. There should be no need to restart containers to see code changes.
```bash
$ docker-compose down
```

## Other Tasks

### Logs
### Automated Tests

- We use [pytest](https://docs.pytest.org/en/latest/contents.html) with the [pytest-django](https://pytest-django.readthedocs.io/en/latest/) plugin for running tests.
- Please add tests for your code when contributing.
- Run the test suite using `docker-compose run --rm app pytest`
- With test coverage report `docker-compose run --rm app pytest --cov-report=term --cov=.`

### Debugging with Docker Logs

View logs from all containers.

```plain
docker-compose logs
```bash
$ docker-compose logs
```

View logs from a single container (in this case the `app` container).

```plain
docker-compose logs app
```bash
$ docker-compose logs app
```

You can use the same structure to view logs for the other containers; `nginx`, `db`, `mailhog`, `adminer`, `app`.
Expand All @@ -95,24 +145,21 @@ If you would like to tail the logs in the console then you remove the detach fla

The following are examples of some common Django management commands that you may need to run.

* Make Migrations: `docker-compose run --rm app ./manage.py makemigrations`
* Merge Migrations: `docker-compose run --rm app ./manage.py makemigrations --merge`
* Run Migrations: `docker-compose run --rm app ./manage.py migrate`
- Make Migrations: `docker-compose run --rm app ./manage.py makemigrations`
- Merge Migrations: `docker-compose run --rm app ./manage.py makemigrations --merge`
- Run Migrations: `docker-compose run --rm app ./manage.py migrate`

To see the full list of management commands use `help`.

```plain
docker-compose run --rm app ./manage.py help
```

### Automated Tests

* We use [pytest](https://docs.pytest.org/en/latest/contents.html) with the [pytest-django](https://pytest-django.readthedocs.io/en/latest/) plugin for running tests.
* Please add tests for your code when contributing.
* Run the test suite using `docker-compose run --rm app pytest`
* With test coverage report `docker-compose run --rm app pytest --cov-report=term --cov=.`
### Postman

### Import Postman collection
<details>
<summary>Importing Postman collection</summary>
<br>
Postman is a free interactive tool for verifying the APIs of your project. You can download it at postman.com/downloads.

Postman is an interactive tool for verifying the APIs of your project in an isolated environment--think of it as a a virtual playground where we can safely experiment and edit our API before we deploy it on our web app--just like virtual environments help us isolate our python dependencies.
Expand All @@ -137,66 +184,84 @@ Linux,
5. Now, as long you have the Django app (https://localhost:8000) running, you should be able to make requests like POST Create User and POST Authenticate.
Click on this link to see what you should expect: https://imgur.com/hd9VB6k

POST Create User will create a new user in your localhost:8000 running Django app, and making a request to POST Authenticate will authenticate whether or not that user exists.
- `POST` Create User will create a new user in your `localhost:8000` running Django app,
- making a request to `POST Authenticate` will authenticate whether or not that user exists.

![screenshot of Postman environment variable setup](https://i.imgur.com/6Uq9XQp.png)

5. Now, as long you have the Django app (https://localhost:8000) running, you should be able to make requests like `POST Create User` and `POST Authenticate` by clicking on the blue "Send" button in Postman.

</details>

## Removing Everything

<details>
<summary>To remove all containers</summary>
<br>
To remove all containers run the following:

```plain
docker-compose rm
```bash
$ docker-compose rm
```

This will leave a copy of the data volume (holding the PostgreSQL data) behind. To remove that you will need to identify and remove the data volume.

```plain
docker volume ls
```bash
$ docker volume ls

DRIVER VOLUME NAME
local django-concept_db_data
```

Note the name of the data volume, in this case `django-concept_db_data` and delete it.

```plain
docker volume rm django-concept_db_data
```bash
$ docker volume rm django-concept_db_data
```

Note: it is likely that cached copies of your container images will be retained by Docker on your local machine. This is done to speed things up if you require these images in future. To completely remove unused container images and networks, we recommend you follow Docker [pruning guide](https://docs.docker.com/config/pruning/).
**Note:** it is likely that cached copies of your container images will be retained by Docker on your local machine. This is done to speed things up if you require these images in future. To completely remove unused container images and networks, we recommend you follow Docker [pruning guide](https://docs.docker.com/config/pruning/).

</details>

## Proof-of-concept Goals

A resource datastore

- save resource
- delete resource
- update resource
- list resource
- search resources
- [x] save resource
- [x] delete resource
- [x] update resource
- [x] list resource
- [x] search resources

Resource:

- title
- description
- type
- credit
- url
- referrer
- [x] title
- [x] description
- [x] type
- [x] credit
- [x] url
- [x] referrer

The start of a resource bookmarking/archiving service.

- Calendar/hangouts
- [ ] Calendar/hangouts
- How easy would it be to make a calendar widget that lets users block out times they're free for hangouts?

# Findings
## Contributing

Please see [How to contribute here]

<!-- TODO: # Findings -->

# Technologies Used
=======
Please see [instructions here](https://github.com/codebuddies/django-concept/wiki/Contribution-instructions)
<!-- TODO: # Technologies Used -->

This project is not deployed yet, but will interact as the API supporting [https://github.com/codebuddies/frontend](https://github.com/codebuddies/frontend)

[Background]: https://github.com/codebuddies/codebuddies/issues/1136
[Cloning a repository]: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository
[Crowdsourced brainstorm of problems we want to solve]: https://pad.riseup.net/p/BecKdThFsevRmmG_tqFa-keep
[Fork a repo]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo
[Getting Started]: https://www.docker.com/products/docker-desktop
[How to contribute here]: https://github.com/codebuddies/django-concept/wiki/Contribution-instructions
[https://github.com/codebuddies/frontend]: https://github.com/codebuddies/frontend
[See PR 127]: https://github.com/codebuddies/backend/pull/129
[The API spec all the proof-of-concept]: https://app.swaggerhub.com/apis-docs/billglover/CodeBuddies/0.0.1

0 comments on commit 31ca929

Please sign in to comment.