Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update readme #138

Merged
merged 2 commits into from
Apr 30, 2020
Merged

docs: update readme #138

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba6f01c
docs: update readme
tgrrr Apr 29, 2020
d7cd7b8
docs: update based on Linda's (@lpatmo) feedback
tgrrr Apr 29, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 137 additions & 72 deletions README.md
View file
Open in desktop
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_
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heh, good note :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ta


## 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]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be linking to codebuddies/codebuddies#1136 and https://app.swaggerhub.com/apis-docs/billglover/CodeBuddies/0.0.1 respectively, right?

So:

The [API spec](https://app.swaggerhub.com/apis-docs/billglover/CodeBuddies/0.0.1) of our proof-of-concept

etc.

- [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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The URL "Getting Started" is linking to is missing here as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link has been moved to the bottom https://github.com/codebuddies/backend/compare/feature/readme-update#diff-04c6e90faac2675aa89e2176d2eec7d8R233

I've used a reference style link format for readability. See [link text itself]: http://www.reddit.com here https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#links

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ohh, TIL! Thanks, didn't know it was possible to do this in markdown before, for some reason 😅


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ohh, one idea here: maybe it would be helpful to add @chris48s' documentation about the init_data --help command:

$ 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

This is from his PR at #129

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done


```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