Installation Guide¶
There are a number of ways to get Janeway up and running. For development we recommend you use Docker with Postgres as the DB_VENDOR. A Lando configuration is also included.
Running Janeway with Docker and docker-compose¶
- Install
docker
,docker-compose
andGNU Make
. - From the /path/to/janeway directory run
make install
. - A docker environment will be provisioned, and shortly after the janeway isntall script will run. Follow the instructions on screen to complete the installation.
- Once install is complete run
make run
to run the django development server against a Postgres backend. - For Janeway browse
http://localhost:8000
/. - If using Postgres (e you can also browse
http://localhost:8001
for pgadmin. The default root password is janeway-web
The Makefile provides a number of other targets for common tasks during development.
make db-client
: Will open a database shell that matches your configuredDB_VENDOR
. (e.g. runningmake db-client
with the default options will run an interactive psql instance from the postgres container)make command
allows you to run django management commands using the CMD variable (e.gmake command CMD=migrate journal
would be equivalent to running python3 src/manage.py migrate journal in a native install)make check
will run Janeway’s test suite with some predetermined configuration options to improve performance:- It runs against a sqlite backend
- database migrations are skipped
- If you want to run the test suite against the database server then run it as a django management command with
make command CMD=test
make attach
: Attach to the running Janeway container and run an interactive shell (a Janeway development server must be running withmake run
for this to work)make shell
: Start a janeway container and run an interactive shell. (It will bind port 8000 on your host so you cannot run this if a janeway server is running, in that case use make attach instead)make rebuild
: Rebuilds the Janeway docker container. It should only be used when you make changes to the dependencies that need to be installed (e.g adding add new library torequirements.txt
)make db-save-backup
: Save a backup of the database container. The command will return the name of the file in which the backup is stored. The backup is created by compressing the entire database container volume.make db-load-backup BACKUP=<backup file>
: Load a previously generated backup. You must set the BACKUP variable to the filename returned by a previous run ofmake db-save-backup
The Makefile can be configured with a number of variables to change the way in which your development environment is run.
- If you want to run janeway against a different database vendor, you can use the DB_VENDOR variable. The following values are supported:
postgres
(default),mysql
orsqlite
- e.g. if you want to install the development environment for Janeway using a mysql container, you can run
make install DB_VENDOR=mysql
for the installation andmake run DB_VENDOR=mysql
to spin up the mysql container alongside the Janeway development server.
- e.g. if you want to install the development environment for Janeway using a mysql container, you can run
- If you want to run janeway against a different database vendor, you can use the DB_VENDOR variable. The following values are supported:
- By default, the database backend will come with a database named
janeway
. If you want to Janeway against a different database (e.g.: you have multiple local databases) you can set the DB_NAME variable (e.g.:make install DB_NAME="janeway_staging"
ormake run DB_NAME=janeway_production
- The
JANEWAY_PORT
variable allows you to change the port to which the Janeway development server will be bound to on your host (set this if port 8000 is already in use by another service on your host)
If you want to install custom python libraries for development, you can drop them into the dev_requirements.txt file and run make rebuild
. Rebuilding the container takes some time, so it is also possible to install python libraries in development mode. When installed in this manner, the library is mounted as a volume into the janeway container when you first run make rebuild and you will be able to make changes to the library without having to run make rebuild
. In order to install a library in development mode, copy the code to /path/to/janeway/lib/
and run make rebuild
once.
Using Lando for a development environment (optional)¶
Lando can be used to construct and manage a local a development environment. Here are the steps required to get Janeway running on your local machine, using Lando:
Note
Lando comes bundled with Docker Desktop for MacOS, if you already have Docker Desktop installed on your Mac, don’t re-install it. You should instead ensure you have the same (or newer) version as what is bundled with Lando.
- Make sure Lando is installed
- Optionally, copy
dockerfiles/lando_local.env.example
todockerfiles/lando_local.env
and customize as appropriate (the database configuration is done with environment variables, so pay attention todockerfiles/lando_local.env
if it’s important to you) lando poweroff
(defensively ensure no other Lando environments are running, probably not necessary, but a good habit)lando rebuild
- When you see the big “Boomshakala” message from Lando, you’re ready to proceed
lando manage check
will confirm the installation is working, and notify you of any misconfigurations- Revise your src/core/settings.py file as directed in the Database Setup and Final Installation instructions below
lando logs -f
will show you the log output from Janeway, though when you’re getting started, lando manage check will help you find configuration errors much faster than sifting through log file outputlando manage <command>
will send commands to the src/core/manage.py script, run lando manage -h to see more infolando manage install_janeway
will continue your installation of Janewaylando manage test
will run the Janeway unit test suitelando python <command>
will send Python commands to the appserver- Browse to http://localhost:8000 to see the site in action
- run
lando
to see what other Lando tooling commands are available.
Lando Tooling¶
lando psql
Drops into the PostgreSQL client running on the database servicelando db-import <file>
Imports a dump file into the database servicelando ssh
Drops into a shell on the application service, runs commandslando start
Starts the Janeway applando stop
Stops the Janeway applando rebuild
Rebuilds the Janeway applando restart
Starts and stops the Janeway app, useful for forcing the app to use new configurationslando destroy
Removes all traces of the Janeway dev environment’s containers, useful if you need to ensure a fresh start
More Lando tooling can be added, if you need it.
Native Install¶
The following is for Debian/Ubuntu-based systems (16.04).
- Install python3, pip3 & virtualevwrapper and create a project
sudo apt-get install python3 python3-pip python-pip virtualenvwrapper
source /etc/bash_completion.d/virtualenvwrapper
mkvirtualenv janeway -p /usr/bin/python3
- Install system dependencies.
On Ubuntu systems:
sudo apt-get install libxml2-dev libxslt1-dev python3-dev zlib1g-dev lib32z1-dev libffi-dev libssl-dev libjpeg-dev libmysqlclient-dev
On Debian systems:
sudo apt-get install libxml2-dev libxslt1-dev python3-dev zlib1g-dev lib32z1-dev libffi-dev libssl-dev libjpeg-dev
Clone the janeway repo to your local machine:
git clone https://github.com/BirkbeckCTP/janeway.git
From the project root directory run the following to install python dependencies:
pip3 install -r requirements.txt
You should now proceed to “Database Setup and Final Installation”, below.
Database Setup and Final Installation¶
Copy the example settings file:
cp src/core/example_settings.py src/core/settings.py
Update settings.py for your env (database login etc.) and setup your database. This must support utf8_mb4. For MySQL installs, use the following CREATE command:
CREATE DATABASE janeway CHARACTER SET = utf8 COLLATE = utf8_general_ci;
From inside the src directory, switch to the virtual environment:
workon janeway
Run the installer
python3 manage.py install_janeway
and follow the on screen instructions.
> Please answer the following questions.
> Press name: Test Press
> Press domain: test.press.com
> Press main contact (email): ajrbyers@gmail.com
> Thanks! We will now set up out first journal.
> Journal #1 code: tstj
> Journal #1 domain: journal.press.com
If you are installing Janeway on a live server rather than on your local development environment its at this point you’ll need to look at a webserver, Django is supported by Apache via mod_wsgi and with NGINX through a variety of tools. We have an [[Apache and mod_wsgi (Server Install)|Janeway,-Apache-and-WSGI]] guide.
- Once the command line installer is complete you can complete the setup process by directing your browser to: http://yourfirstjournal.com/install/