diff --git a/aimmo/admin.py b/aimmo/admin.py index ce1882f8b..91387a6b2 100644 --- a/aimmo/admin.py +++ b/aimmo/admin.py @@ -1,5 +1,4 @@ from django.contrib import admin - from models import Avatar, Game @@ -11,5 +10,19 @@ class GameDataAdmin(admin.ModelAdmin): def players(self, obj): return "\n".join([u.first_name for u in obj.can_play.all()]) -admin.site.register(Avatar) + +class AvatarDataAdmin(admin.ModelAdmin): + list_display = ['id', 'game_identifier', 'game_name', 'owner_name'] + + def owner_name(self, obj): + return obj.owner + + def game_name(self, obj): + return obj.game.name + + def game_identifier(self, obj): + return obj.game.id + + admin.site.register(Game, GameDataAdmin) +admin.site.register(Avatar, AvatarDataAdmin) diff --git a/aimmo_runner/minikube.py b/aimmo_runner/minikube.py index fd32101ef..7a333efd0 100644 --- a/aimmo_runner/minikube.py +++ b/aimmo_runner/minikube.py @@ -1,6 +1,8 @@ #!/user/bin/env python from __future__ import print_function +from subprocess import CalledProcessError + import docker import kubernetes import os @@ -74,10 +76,10 @@ def start_cluster(minikube): Starts the cluster unless it has been already started by the user. :param minikube: Executable minikube installed beforehand. """ - status = run_command([minikube, 'status'], True) - if 'minikube: Running' in status: + try: + run_command([minikube, 'status'], True) print('Cluster already running') - else: + except CalledProcessError: run_command([minikube, 'start', '--memory=2048', '--cpus=2']) diff --git a/docs/usage.md b/docs/usage.md index 17b9a56da..677e9a8ac 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,68 +1,120 @@ # Usage -- [Running Locally with no containers](#running-locally-with-no-containers) -- [Running with Kubernetes with containers](#running-with-kubernetes-with-containers) -- [Testing Locally](#testing-locally) -- [Useful Commands](#useful-commands) ---- - -## Running Locally with no containers -* Follow the instructions at [game frontend documentation](https://github.com/ocadotechnology/aimmo/blob/master/game_frontend/README.md) in order to install all the frontend requirements. -* Make and activate a virtualenv (We recommend [pipenv](https://docs.pipenv.org/)). - * On **Mac**, run `brew install pipenv` using the `brew` package manager. Then run `pipenv install` followed by `pipenv shell`. - * On **Ubuntu**, run `sudo bash ubuntu_setup.sh`. This will install nodejs, yarn, as well as pipenv. Now run the following: `pipenv shell`. -* `./run.py` in your aimmo dir - This will: - * if necessary, create a superuser 'admin' with password 'admin' - * install all of the dependencies using pip - * sync the database - * collect the static files - * run the server -* You can quickly create players as desired using the following command: - - `python example_project/manage.py generate_players 5 dumb_avatar.py` - - This creates 5 users with password `123`, and creates for each user an avatar that runs the code in `dumb_avatar.py` -* To delete the generated players use the following command: - -`python example_project/manage.py delete_generated_players` - - -## Running with Kubernetes with containers -**64bit environment is required for this mode!** -* Follow the instructions at [game frontend documentation](https://github.com/ocadotechnology/aimmo/blob/master/game_frontend/README.md) in order to install all the frontend requirements. -* By default, the local environment runs each worker in a Python thread. This is the closest mode that reflects the environment in production. However, this will require much more resources. -* Linux, Windows, and OSX. -* Prerequisites: - * All platforms: VT-x/AMD-v virtualization. - * Linux: [Virtualbox](https://www.virtualbox.org/wiki/Downloads). - * OSX: either [Virtualbox](https://www.virtualbox.org/wiki/Downloads) or [VMWare Fusion](http://www.vmware.com/products/fusion.html). -* To download Docker, Minikube, and Kubectl before running the script. - * On Mac ([download homebrew](https://brew.sh/)) and run `brew update && brew cask install docker virtualbox`. - * Install a fixed minikube version (at the time of this article this is 0.25.2 but you can confirm that [here](https://github.com/ocadotechnology/aimmo/blob/b0fd1bf852b1b2630a8546d173798ec9a670c480/.travis.yml#L23)). To do this write - `curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.25.2/minikube-darwin-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/ - ` and replace the version with the desired one. - * Install kubectl: - `curl -Lo kubectl https://storage.googleapis.com/kubernetes-release/release/v1.9.4/bin/darwin/amd64/kubectl && chmod +x kubectl && sudo mv kubectl /usr/local/bin/` - * On Ubuntu ([download snap](https://snapcraft.io/)) and run `sudo snap install kubectl --classic` then follow the ([docker installation instructions](https://docs.docker.com/install/linux/docker-ce/ubuntu/)). - * On Windows ([download chocolatey](https://chocolatey.org/)) and run `choco install kubernetes-cli` followed by the ([docker installation instructions for Windows](https://docs.docker.com/docker-for-windows/)). -* Alter your `/etc/hosts` file by adding the following to the end of the file: `192.168.99.100 local.aimmo.codeforlife.education`. You may be required to run this with `sudo` as the file is protected. -* Usage: `python run.py -k`. This will: - * Run `minikube start --memory=2048 -cpus=2`. Feel free to change these values appropriately to your specifiation. - * Images are built and a aimmo-game-creator is created in your cluster. You can preview this in your kubernetes dashboard. Run `minikube dashboard` to open this. - * Perform the same setup that run.py normally performs. - * Start the Django project (which is not kubernetes controlled) on localhost:8000. -* Run the same command to update all the images. - -### Interacting with the cluster - -* `kubectl` and `minikube` can be used to interact with the cluster. +- [Mac setup](#mac-setup) +- [Ubuntu/Debian setup](#ubuntu-setup) +- [Windows setup](#windows-setup) +- [Testing locally](#testing-locally) +- [Useful information](#useful-information) + +## Mac setup + +This can be done either manually or using the setup script. + +#### Install using the setup script: + +* Run `python aimmo_setup.py` in the AI:MMO root directory. Then: +* Open Docker to finalise the install process. (This will install the [latest release](https://www.docker.com/get-started)) +* Get the latest Unity bundle release from the [aimmo-unity](https://github.com/ocadotechnology/aimmo-unity) repo. +* See [Useful information](#useful-information) for additional details about the script. + +#### Install manually: + +* First you get the [brew](https://brew.sh/) package manager. Then: +* Follow the instructions at [game frontend documentation](https://github.com/ocadotechnology/aimmo/blob/master/game_frontend/README.md) in order to set up the frontend requirements, (you should be in the game_frontend folder for this step). +* Run `brew install pipenv`, followed by `pipenv install`, then `pipenv shell`. This will get and activate the virtualenv we recommend for the project. (more information on [pipenv](https://pipenv.readthedocs.io/en/latest/)) + +The game should now be set up to run locally (If you ran the setup script, it will have done these next steps for you). If you wish to be able to run the project with [Kubernetes](https://kubernetes.io/) and containers, follow these next steps: + +* Install both [Docker](https://www.docker.com/) and [Virtualbox](https://www.virtualbox.org/wiki/Downloads), using: + * `brew update && brew cask install docker virtualbox` +* Install a fixed version of Minikube, (current version is 0.25.2, this can be confirmed [here](https://github.com/ocadotechnology/aimmo/blob/b0fd1bf852b1b2630a8546d173798ec9a670c480/.travis.yml#L23)). To get this, run: + * `curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.25.2/minikube-darwin-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/` +* To install kubectl (Kubernetes), use: + * `curl -Lo kubectl https://storage.googleapis.com/kubernetes-release/release/v1.9.4/bin/darwin/amd64/kubectl && chmod +x kubectl && sudo mv kubectl /usr/local/bin/` +* Alter your `/etc/hosts` file by adding the following line to the end of the file: `192.168.99.100 local.aimmo.codeforlife.education`. You may need to use sudo for this step as the file is protected. +* Get the latest Unity bundle release from the [aimmo-unity](https://github.com/ocadotechnology/aimmo-unity) repo. + +#### To run AI:MMO: + +* Ensure you are inside the python virtualenv, `pipenv shell`. +* To run **locally**, use: `python run.py`. +* If you want to run the project with [Kubernetes](https://kubernetes.io/), first run: `minikube start`. +* Now use `python run.py -k` to run the project using the Kubernetes cluster. + +## Ubuntu setup + +This can be done either manually or using the setup script. + +#### Install using the setup script: + +* Run `python aimmo_setup.py` in the AI:MMO root directory. Then: +* Get the latest Unity bundle release from the [aimmo-unity](https://github.com/ocadotechnology/aimmo-unity) repo. +* See [Useful information](#useful-information) for additional details about the script. + +#### Install manually: + +* First run `sudo apt-get update` to save having to do it later in the process. +* Follow the instructions at [game frontend documentation](https://github.com/ocadotechnology/aimmo/blob/master/game_frontend/README.md) in order to set up the frontend requirements, (you should be in the `game_frontend` folder for this step). +* Next run `sudo apt-get install python-pip`, followed by `pip install pipenv` to get the [pipenv](https://pipenv.readthedocs.io/en/latest/)) virtual environment. +* Now use `pipenv install` and `pipenv shell` to get the requirements for the project and enter the virtualenv. + +The game should now be set up to run locally (If you ran the setup script, it will have done these next steps for you). If you wish to be able to run the project with [Kubernetes](https://kubernetes.io/) and containers, follow these next steps: + +* If not already installed follow the [Virtualbox installation instructions](https://www.virtualbox.org/wiki/Downloads). +* Install [Snap](https://snapcraft.io/)) using `sudo apt install snapd`. +* Now run `sudo snap install kubectl --classic` to install kubectl ([Kubernetes](https://kubernetes.io/)). +* To install [Docker](https://www.docker.com/), either use `sudo apt-get install docker-ce` to install a fixed version of the latest release, or follow the Ubuntu install instructions on the [Docker website](https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-using-the-repository). +* Alter your `/etc/hosts` file by adding the following line to the end of the file: `192.168.99.100 local.aimmo.codeforlife.education`. You may need to use sudo for this step as the file is protected. +* Get the latest Unity bundle release from the [aimmo-unity](https://github.com/ocadotechnology/aimmo-unity) repo. + +#### To run AI:MMO: + +* Ensure you are inside the python virtualenv, `pipenv shell`. +* To run **locally**, use: `python run.py`. +* If you want to run the project with [Kubernetes](https://kubernetes.io/), first run: `minikube start`. +* Now use `python run.py -k` to run the project using the Kubernetes cluster. + +## Windows setup + +#### Install Manually: + +* Contact a member of the Code for Life team via the [Code for Life contact form](https://www.codeforlife.education/help/#contact). + +The game should now be set up to run locally. If you wish to be able to run the project with [Kubernetes](https://kubernetes.io/) and containers, follow these next steps: + +* If not already installed follow the [Virtualbox installation instructions](https://www.virtualbox.org/wiki/Downloads). +* Next, [download chocolatey](https://chocolatey.org/) and run `choco install kubernetes-cli`. +* Then follow the [docker installation instructions for Windows](https://docs.docker.com/docker-for-windows/). +* Alter your `/etc/hosts` file by adding the following line to the end of the file: `192.168.99.100 local.aimmo.codeforlife.education`. You may need admin privileges for this step as the file is protected. + +#### To run AI:MMO: + +* Ensure you are inside the python virtualenv, `pipenv shell`. +* To run **locally**, use: `python run.py`. +* If you want to run the project with [Kubernetes](https://kubernetes.io/), first run: `minikube start`. +* Now use `python run.py -k` to run the project using the Kubernetes cluster. + +## Useful information + +Here you can find some other useful information regarding the setup or usage of various aspects of the project. + +#### Setup script & other setup information. + +* It may be the case that the frontend does not load properly upon starting aimmo (when running the script). If this is the case then you may need to follow the [game frontend documentation](https://github.com/ocadotechnology/aimmo/blob/master/game_frontend/README.md) in order to resolve this (usually all the packages are there, it just requires you to set them up manually). +* If the script fails when attempting to install Docker, it may be because you have an old version of docker currently installed. To fix this, run: `sudo apt-get remove docker docker-engine docker.io`, then re-run the script. +* If there is an issue when using containers or the virtual enviroment. Then there small chance that VT-x/AMD-x virtualization has not been enabled on your machine. If this is the case the main way to solve this is to enable it through the BIOS settings. + +#### Testing locally + +* Use `./all_tests.py` to run all the tests (note that this is several pages of output). +* The `--coverage` option will generate coverage data for the tests using `coverage.py`. + +#### Interacting with the cluster + +* `kubectl` and `minikube` can be used to interact with the cluster. * Running either command without any options will give the most useful commands. -* `minikube dashboard` to open the kubernetes dashboard in your browser. +* Use `minikube dashboard` to open the [Kubernetes](https://kubernetes.io/) dashboard in your browser. -## Testing Locally -*`./all_tests.py` will run all tests (note that this is several pages of output). -* `--coverage` option generates coverage data using coverage.py +#### Useful commands -## Useful Commands -* To create an another admin account: -`python example_project/manage.py createsuperuser` - * By default, we create an admin account with credentials admin:admin when you start the project. +* To create an another admin account: `python example_project/manage.py createsuperuser` + * By default, we create an admin account with credentials admin:admin when you start the project.