You can use Vagrant to set up a virtual machine for local development and testing. This is useful to keep your development environment isolated from the rest of your system.
First, install VirtualBox and Vagrant. Then run:
vagrant up
This will provision a virtual machine running Ubuntu 14.04, set up local Postgres and Redis, install the dependencies and run the tests.
Once the virtual machine is up and running, you can ssh into it with this command:
vagrant ssh
Vagrant will set up a VirtualBox share mapping your local development directory
to /vagrant
inside the virtual machine. Any changes you make locally will be
reflected inside the virtual machine automatically.
Vagrant will map port 5000 inside the virtual machine to port 5000 on the host, so you can access the development server using your web browser.
If you prefer not to install Vagrant, you can install OpenCraft manually. Refer to the bootstrap script used by Vagrant for an example. Instructions based on Ubuntu 14.04.
Install the system package dependencies & virtualenv:
$ make install_system_dependencies
$ pip3 install --user virtualenv && pip3 install --user virtualenvwrapper
You might also need to install PostgreSQL:
$ make install_system_db_dependencies
Ensure you load virtualenv with Python 3 in ~/.bashrc
:
export PATH="$PATH:$HOME/.local/bin" VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
source $HOME/.local/bin/virtualenvwrapper.sh
Then reload ~/.bashrc
, create the virtual env and install the Python requirements:
$ . ~/.bashrc
$ mkvirtualenv -p /usr/bin/python3 opencraft
$ workon opencraft
$ pip install -r requirements.txt
Honcho will set up environment variables defined in the .env
file at the root
of your repository. If you are using vagrant for development, a basic .env
file will already have been created for you, but you will need to add
credentials for third-party services manually in order to run the development
server or the integration tests.
The environment variables in .env
customize the settings from
opencraft/settings.py
which are loaded via env()
.
To run database migrations:
$ make migrate
The startup commands such as make run
and make rundev
check for pending migrations, and will
exit before starting the server if any are found. You can also check for pending migrations manually with:
$ make migration_check
In order to login to the development server locally you will need to create a superuser through
honcho run ./manage.py createsuperuser
Once created, you will be able to logon to your locally-host instance with the username and password you set up.
To run the development server:
$ make rundev
Then go to:
- User interface: http://localhost:5000/
- API: http://localhost:5000/api/
- Admin: http://localhost:5000/admin/
To run the production server:
$ make run
To change the number of concurrent workers ran by the production server:
$ make run WORKERS=2
This runs three processus via Honcho, which reads Procfile
or Procfile.dev
and loads the
environment from the .env
file:
- web: the main HTTP server (Django - Werkzeug debugger in dev, gunicorn in prod)
- websocket: the websocket server (Tornado)
- worker: runs asynchronous jobs (Huey)
Important: the Werkzeug debugger started by the development server allows remote execution of Python commands. It should not be run in production.
The Web server started in the development environment also doesn't require collectstatic to run after each change.
The production environment automatically runs collectstatic on startup, but you can also run it manually:
$ make collectstatic
First, the current user can access PostgreSQL and create databases, for the test database. Run:
$ sudo -u postgres createuser -d <currentunixuser>`
Where <currentunixuser>
is replaced with the name of whatever user the app runs under. Then run
the whole test suite (pylint, pyflakes, pep8, unit tests, etc.) with:
$ make test
To run a single test, use make test_one
:
$ make test_one instance.tests.models.test_server
You can also run Prospector, the unit tests, JS tests and integration independently:
$ make test_prospector
$ make test_unit
$ make test_js
$ make test_integration
JS tests can be run in your browser for debugging (see make test_js_web
and then go to
http://localhost:8888/ ), or in a CI manner via selenium and jasmine-ci
(see make test_js
).
Note that the integration tests aren't run by default, as they require a working
OpenStack cluster configured. To run them, create a .env.integration
file -
your development environment is likely a good starting point:
$ ln -s .env .env.integration
To access the console, you can use shell_plus
:
$ make shell
You can also access the Django manage.py
command directly, using Honcho to load the environment:
$ honcho run ./manage.py config