Merge pull request #1 from commoncode/feature/initial-setup

Initial Setup

Author: Simeon J Morgan

README.md

@@ -0,0 +1,15 @@
+# The Pacific Connect Community Database
+
+The [Pacific Connect](https://www.icdp.com.au/pacific-connect/) community database provides a
+means for participants in Pacific Connect to find details for one another and to maintain their own contact details through a
+web portal.
+
+It is being developed as part of the Vanuatu Code Project.
+
+## Getting started
+
+1. Install a git client (such as the GitHub Desktop application from https://desktop.github.com/)
+2. Clone this repository. (If using GitHub Desktop, there is [documentation for cloning a
+   repository](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop))
+3. Open the `Getting Started` documentation in `/docs/getting-started.md` and follow the steps for local development
+   set-up.

docs/getting-started.md

@@ -0,0 +1,156 @@
+# Getting Started
+
+This page describes the steps needed to get the Pacific Connect Community Database set up on your local machine for development. The
+approach presented here is the simplest approach, an alternative approach is briefly mentioned under [Alternative
+Approach: Pyenv](#alternative-approach-pyenv) at the end.
+
+It assumes that you have already cloned this repository to your own computer (as outlined in the `README.md` file) and
+that you have a recent version of Python installed on your local computer.
+
+Python installation instructions for several operating systems can be found at
+http://pacific-coding.commoncode.io/getting-started/py-install/ - although you should install version 3.10 if possible
+
+
+## Requirements
+
+- A Git client (such as GitHub Desktop)
+- This repository _cloned_ or your local computer.
+- Python 3.8 or later installed
+
+## Setup Steps
+
+To carry out these steps, you will need to be using your computer's _command line_. If you are not familiar with the
+concept of the command line an introduction can be found at
+http://pacific-coding.commoncode.io/getting-started/terminal/
+
+On the command line, you will need to be in the base directory of this repository on your computer - that is, the
+directory that has the `README.md` file in it.
+
+### 1. Create and activate a virtual environment
+
+A _virtual environment_ (or _virtualenv_) in Python keeps the different _libraries_ you install separate for different
+projects. That means that if you're working on two different projects, they can have different versions of the same
+library (e.g. Django) without affecting each other.
+
+Create the virtual environment for this project:
+
+If using Windows:
+```powershell
+python -m venv venv
+```
+
+If using MacOS or Linux:
+```bash
+python3 -m venv venv
+```
+
+Once you have created your virtual environment, you need to _activate_ it so that Python knows to use the libraries in
+your virtual environment.
+
+To activate your virtual environment:
+
+If using Windows:
+```powershell
+venv\Scripts\activate
+```
+
+If using MacOS or Linux:
+```
+source venv/bin/activate
+```
+
+If your virtual environment has been activated, you should see the prefix `(venv)` before the prompt on the command
+line.
+
+**NOTE: You will need to activate your virtual environment every time you want to work on this project**.
+
+For more information about virtual environments, see:
+- [Why do we need to use virtualenvs](http://pacific-coding.commoncode.io/python-intro/virtualenvs/)
+- [Create a Virtual Environment](http://pacific-coding.commoncode.io/python-intro/create-a-venv/)
+
+ 
+### 2. Install the Python requirements
+
+This project has a `requirements.txt` file that lists all the Python libraries required to run the project. Once you
+have activated your virtual environment, you can install the python libraries with:
+
+```bash
+pip install -r requirements.txt
+```
+
+This will install all requirements listed in the `requirements.txt` file, and as new requirements are added to the
+project they will be added to the `requirements.txt` file.
+
+
+### 3. Run migrations
+
+Migrations are the way that Django manages changes to the structure of the database over time.
+
+Before running migrations, you will need to change to the directory (`src`) that contains the code. Different projects
+have different conventions about the name of the directory where the code is kept, but `src` is a common name.
+
+```bash
+cd src
+```
+
+To set up your database the first time, run:
+
+Windows:
+```bash
+python manage.py migrate
+```
+
+MacOS or Linux:
+```bash
+python3 manage.py migrate
+```
+
+The first time you run this, you will see a series of messages that look like:
+
+```
+Operations to perform:
+  Apply all migrations: admin, auth, contenttypes, sessions
+Running migrations:
+  Applying contenttypes.0001_initial... OK
+  Applying auth.0001_initial... OK
+  Applying admin.0001_initial... OK
+  Applying admin.0002_logentry_remove_auto_add... OK
+  ...
+```
+
+This indicates that the migrations have run and the database is set up.
+
+**NOTE: You will need to run migrations fairly regularly in order to keep your database structure up to date**
+
+A summary about database set-up in Django can be found at:
+- [Pacific Coding: Set up a
+  Database](http://pacific-coding.commoncode.io/django/your-first-django-project/#set-up-a-database)
+
+More information in Migrations can be found at:
+- [Django's Migrations documentation](https://docs.djangoproject.com/en/4.0/topics/migrations/)
+
+More information on Models can be found at:
+- [MDN's Django Tutorial Part 3](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Django/Models)
+- [Django's Models documentation](https://docs.djangoproject.com/en/4.0/topics/db/models/)
+
+
+### 4. Continue to _Running the Application_
+
+Now that you have installed all the prerequisites and run migrations for the first time, you can move to
+[running-the-application].
+
+## Alternative Approach: Pyenv
+
+This approach is only recommended if you need to run multiple different versions of Python (such as Python 3.8 _and_
+Python 3.10) on the same computer.
+
+[Pyenv](https://github.com/pyenv/pyenv) is a tool that allows you to have multiple Python versions installed and switch
+between them. When combined with [Pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) it also provides the
+ability to easily switch between named virtual environments.
+
+To install, see the instructions at [Pyenv Installation](https://github.com/pyenv/pyenv#installation) and
+[Pyenv-virtualenv Installation](https://github.com/pyenv/pyenv-virtualenv#installation)
+
+
+
+[running-the-application]: running-the-application.md

docs/glossary.md

@@ -0,0 +1,4 @@
+# Glossary
+
+- **venv**: Virtual environment
+- **virtualenv**: Virtual environment

docs/index.md

@@ -0,0 +1,17 @@
+# Pacific Connect Community Database
+
+## About
+
+The Pacific Connect Community Database is a web-based directory for Pacific Connect participants. It has been developed by participants in the
+Vanuatu Code Project. 
+
+## Contents
+
+1. [Getting Started][getting-started] - Step by step instructions to set up your development environment
+2. [Running the application][running-the-application] - Step by step instructions to set up your development
+   environment
+3. [Glossary][glossary] - A Glossary of terms and acronyms
+
+[getting-started]: getting-started.md
+[running-the-application]: running-the-application.md
+[glossary]: glossary.md

docs/running-the-application.md

@@ -0,0 +1,101 @@
+# Running the Application
+
+Once you have completed the set-up of the development environment from the [Getting Started][getting-started] page, you
+can start and use the application on your local computer.
+
+This page assumes that you are on the _command line_, in the directory containing the `README.md` file for this project.
+For more information about the command line, see the [Getting Started][getting-started] page.
+
+If you have just come from the Getting Started documentation, you may be in the `src` directory. To move out of this directory, on the command line do:
+
+```bash
+cd ..
+```
+
+That command will move you 'up' a directory, out of the `src` directory.
+
+### 1. Activate your virtual environment
+
+If your Python virtual environment is not already activated, activate it:
+
+If using Windows:
+```powershell
+venv\Scripts\activate
+```
+
+If using MacOS or Linux:
+```
+source venv/bin/activate
+```
+
+You will need to do this every time you are working with this project on the command line.
+
+
+### 2. Run migrations
+
+In _Getting Started_ you will have run migrations for the first time. It is a good practice to run migrations every
+time you _pull_ changes from the GitHub repository in case those changes included database migrations.
+
+First, move back into the `src` directory:
+
+```bash
+cd src
+```
+
+Then run the migrations with:
+
+Windows:
+```bash
+python manage.py migrate
+```
+
+MacOS or Linux:
+```bash
+python3 manage.py migrate
+```
+If there are no database changes, you will see a message like:
+```
+Operations to perform:
+  Apply all migrations: admin, auth, contenttypes, sessions
+Running migrations:
+  No migrations to apply.
+```
+
+Otherwise, if there have been database changes you will see a list of applied migrations, like:
+```
+Operations to perform:
+  Apply all migrations: admin, auth, contenttypes, sessions
+Running migrations:
+  Applying contenttypes.0001_initial... OK
+  ...
+```
+
+More information in Migrations can be found at:
+- [Django's Migrations documentation](https://docs.djangoproject.com/en/4.0/topics/migrations/)
+
+More information on Models can be found at:
+- [MDN's Django Tutorial Part 3](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Django/Models)
+- [Django's Models documentation](https://docs.djangoproject.com/en/4.0/topics/db/models/)
+
+
+### 3. Run the development server
+
+Django incorporates its own development web server. This gives you a way to interact with the application without
+needing a server on the Internet running it. In this mode, it will also present you with more detailed error messages.
+
+To start the development server, run:
+
+```bash
+python manage.py runserver
+```
+
+Once the server has started running, you can open it in your browser (Firefox, Chroma, Safari, Edge, or whatever you
+use) by going to this address:
+```
+http://127.0.0.1:8000/
+```
+
+You should now see the ICDP Online Directory application in your web browser.
+
+
+[getting-started]: getting-started.md

requirements.txt

@@ -0,0 +1,26 @@
+#
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
+#
+#    pip-compile requirements.in
+#
+asgiref==3.5.2
+    # via django
+black==22.6.0
+    # via -r requirements.in
+click==8.1.3
+    # via black
+django==4.1
+    # via -r requirements.in
+isort==5.10.1
+    # via -r requirements.in
+mypy-extensions==0.4.3
+    # via black
+pathspec==0.9.0
+    # via black
+platformdirs==2.5.2
+    # via black
+sqlparse==0.4.2
+    # via django
+tomli==2.0.1
+    # via black

src/community_db/__init__.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.

src/community_db/admin.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class CommunityDbConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "community_db"