peeringdb-peeringdb/docs/container.md

# PeeringDB Container

## Start a developer instance


### Install and Run Docker

PeeringDB runs inside a Docker container. Docker Compose is used to build both the PeeringDB container and a MySQL server container for testing.

Make sure the ```docker``` and ```docker-compose``` commands are installed on your system, and that the Docker Engine is running. Docker Desktop for Mac/Windows (>=2.5.0.1) includes these tools and they are also available for various POSIX systems. Ensure that ```docker-compose version``` indicates at least version 1.25.4, and that ```docker version``` indicates Engine version at least 19.03.5 and does not report any connection errors to Docker Engine. Connection errors may indicate a need to start the engine.

### Fork the PeeringDB repository, Clone it, Set upstream

Your development and experimentation with the PeeringDB code base should take place in a [fork of the project](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo).  When you have improvements or fixes to share, you will be able to point other developers to your code, or submit a pull request.

Navigate to [https://github.com/peeringdb/peeringdb](https://github.com/peeringdb/peeringdb).

In the top-right corner of the page, click **Fork**.

On GitHub, navigate to *your* fork of the PeeringDB repository.

Above the list of files, click **Code**.  Copy the HTTPS URL.  It will be something like: ```https://github.com/YOUR-USERNAME/peeringdb.git```

Perform the following:

```sh
PDBHOME=~/src/peeringdb    # Adjust as appropriate to your environment.
mkdir -p $PDBHOME && cd $PDBHOME
git clone https://github.com/YOUR-USERNAME/peeringdb.git
cd $PDBHOME/peeringdb      # Henceforth commands on this page assume you are in this working directory.
git remote add upstream https://github.com/peeringdb/peeringdb.git
git remote -v
> origin	https://github.com/YOUR-USERNAME/peeringdb.git (fetch)
> origin	https://github.com/YOUR-USERNAME/peeringdb.git (push)
> upstream	https://github.com/peeringdb/peeringdb.git (fetch)
> upstream	https://github.com/peeringdb/peeringdb.git (push)
```

Keep your fork up-to-date with the upstream repository: [https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)

```sh
git fetch upstream
git checkout master    # or other branch you are working on
git merge upstream/master
```

### Create environment variable override file

Environment variables for the server config can be added in `Ctl/dev/.env`.
This file can be empty which will make the django `SECRET_KEY` ephemeral, but
the file does need to exist.

Empty file:

```sh
touch Ctl/dev/.env
```

Alternatively, create a `SECRET_KEY` using `uuidgen` or replace with something similar on your system:

```sh
echo SECRET_KEY=\"$(uuidgen)\" > Ctl/dev/.env
```

### Build the container and set up your dev instance

```sh
./Ctl/dev/compose.sh build peeringdb
./Ctl/dev/compose.sh up -d database
./Ctl/dev/run.sh migrate            # Re-run if there are errors.  The database may not yet have started.
./Ctl/dev/run.sh createsuperuser
./Ctl/dev/run.sh createcachetable
./Ctl/dev/compose.sh up -d peeringdb
```

On some docker versions `build` can fail with a `ERROR: Service 'peeringdb' failed to build: failed to export image: failed to create image: failed to get layer` error. Simply
running it again should fix the issue.


If you want a copy of the current *public* production data, run this command which often takes more than 15 minutes:

```sh
./Ctl/dev/run.sh pdb_load_data --commit
```

After it is done you should have a PeeringDB instance exposed on port `:8000`: [http://127.0.0.1:8000/](http://127.0.0.1:8000/)

(should you want to change this port you can do so by setting the environment variable `DJANGO_PORT`)

### Stop and start the containers

```sh
./Ctl/dev/compose.sh down
./Ctl/dev/compose.sh up -d
```

### Environment Variables

Edit ```Ctl/dev/.env``` and then stop and start the containers.

- `PDB_NO_MIGRATE`: If set to anything, will skip migrations when running the `uwsgi` command, otherwise, migrations will always be applied first thing while running `uwsgi`.
- `DATABASE_ENGINE` default "mysql"
- `DATABASE_HOST` default "127.0.0.1"
- `DATABASE_PORT` default ""
- `DATABASE_NAME` default "peeringdb"
- `DATABASE_USER` default "peeringdb"
- `DATABASE_PASSWORD` default ""
- `EMAIL_HOST` default "localhost"
- `EMAIL_PORT` default "25"
- `EMAIL_HOST_USERHOST` default ""
- `EMAIL_HOST_PASSWORD` default ""

### Mount points

- `/srv/www.peeringdb.com/api-cache`: api cache
- `/srv/www.peeringdb.com/locale`: translations
- `/srv/www.peeringdb.com/mainsite`: site settings
- `/srv/www.peeringdb.com/media`: media files
- `/srv/www.peeringdb.com/peeringdb_server`: server code
- `/srv/www.peeringdb.com/static`: static files
- `/srv/www.peeringdb.com/var/log`: log files

### Entry point

With the exception of some specific commands (see below) the entry point will pass directly to django's manage script.

```sh
./Ctl/dev/run.sh help
```

Other options:

- `migrate` apply database migrations
- `run_tests` run unit tests
- `uwsgi` start the uwsgi process
- `/bin/sh` to drop to shell
- `inetd` run the inetd whois server

### Contributing your code

After testing and carefully code-reviewing your changes, commit and push them to your repository. You can then share the changes with other developers, such as those on the <pdb-tech@lists.peeringdb.com> mailing list: [https://lists.peeringdb.com/cgi-bin/mailman/listinfo/pdb-tech](https://lists.peeringdb.com/cgi-bin/mailman/listinfo/pdb-tech)

When ready to contribute the change to the project, create a pull request to the main repository along with a description of your goals for the change and/or what you are fixing.