diff --git a/.lando.yml b/.lando.yml index 212d724fbf..0a1b220206 100644 --- a/.lando.yml +++ b/.lando.yml @@ -3,8 +3,8 @@ name: janeway # CAREFUL with this env file, Docker env files don't support interpolation! env_file: - - defaults.env - - local.env + - etc/defaults.env + - etc/local.env services: appserver: @@ -14,7 +14,7 @@ services: - grep '^deb ' /etc/apt/sources.list | perl -pe 's/deb /deb-src /' >> /etc/apt/sources.list - apt-get update -qq && apt-get install -y python3-lxml pylint libxml2-dev libxslt1-dev python3-dev zlib1g-dev lib32z1-dev libffi-dev libssl-dev libjpeg-dev && apt-get build-dep -y lxml build: - - cd /app && pip install --upgrade pip && pip install Cython && pip install -r requirements.txt && pip install -r dev-requirements.txt + - cd /app && pip install --upgrade pip && pip install Cython && pip install psycopg2 && pip install -r requirements.txt && pip install -r dev-requirements.txt scanner: true overrides: ports: diff --git a/README.md b/README.md index 28048e37ea..42b3f089cf 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Janeway is written in Python (3.5+) and utilises the Django framework (1.11 LTS) # Installation instructions -Developer installation [instructions are available on our Wiki](https://github.com/BirkbeckCTP/janeway/wiki/Installation). +Developer installation [instructions are available in our documentation site](https://janeway.readthedocs.io/en/feature-documentation/installation.html#installation-guide). A guide for installing on the live environment with [apache and mod_wsgi](https://github.com/BirkbeckCTP/janeway/wiki/Janeway%2C-Apache-and-WSGI) is also available. @@ -24,37 +24,6 @@ In order to run a different RDBMS, the environment variable ``DB_VENDOR`` can be Uninstalling Janeway is as simple as running ``make uninstall`` which will delete all related containers as well as wipe the database volume. -# Using Lando for an alternative development environment (optional) - -Lando provides a simple-to-use alternative to managing a development environment, while maintaining future flexibility to alter different aspects of the environment. Here are the steps required to get the app running on your local machine, with Lando -1. Make sure [Lando](https://lando.dev/) is installed - > Lando comes bundled with Docker Desktop, if you already have Docker Desktop installed, don't re-install it, just ensure you have the same (or newer) version as what is bundled with Lando. -2. Copy `local.env.example` to `local.env` and customize as appropriate (the database configuration is done with environment variables, so pay attention to `local.env` if it's important to you--however, the `defaults.env` file should be sufficient to get started) -3. `lando poweroff` (defensively ensure no other Lando environments are running, probably not necessary, but a good habit) -4. `lando rebuild` -5. When you see the big "Boomshakala" message from Lando, you're ready to proceed -6. `lando django-admin check` will validate the installation is working -7. Revise your src/core/settings.py file as directed in the [Installation](https://janeway.readthedocs.io/en/feature-documentation/installation.html#database-setup-and-final-installation) instructions -8. `lando logs -f` will show you the log output from Django, though when you're getting started, `lando django-admin check` will help you find configuration errors much faster than sifting through log file output -9. `lando manage ` will send commands to the src/core/manage.py script, run `lando manage -h` to see more info -10. `lando manage install_janeway` will continue your installation of Janeway -11. `lando manage test` will run the Janeway unit test suite -11. `lando python ` will send Python commands to the appserver -12. Browse to `http://localhost:8000` to see the site in action -13. run `lando` to see what other Lando tooling commands are available. - -# Lando Tooling -* `lando psql` Drops into the PostgreSQL client running on the database service -* `lando db-import ` Imports a dump file into the database service -* `lando ssh` Drops into a shell on the application service, runs commands -* `lando start` Starts the Janeway app -* `lando stop` Stops the Janeway app -* `lando rebuild` Rebuilds the Janeway app -* `lando restart` Simply starts and stops the Janeway app -* `lando destroy` Removes all traces of the Janeway dev environment's containers, useful if you need to ensure a fresh start - -More Lando [tooling](https://docs.lando.dev/config/tooling.html) can be added easily. - # Janeway design principles 1. No code should appear to work "by magic". Readability is key. diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 1e1ed5766e..c5de213503 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,7 +1,7 @@ Installation Guide ================== -Janeway includes and environment setup script that will install virtual +Janeway includes an environment setup script that will install virtual environment, its apt requirements and pip requirements. Please read the script to ensure it wont cause any issues with your current install. The command can be called directly from the command line: @@ -17,6 +17,48 @@ This command has been tested in 14.04, 15.04 and 16.04 You should now proceed to “Database Setup and Final Installation”, below. +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, if you already have Docker + Desktop installed, don't re-install it. You should instead ensure you have the + same (or newer) version as what is bundled with Lando. + +1. Make sure `Lando `_ is installed +2. Optionally, copy ``local.env.example`` to ``local.env`` and customize as appropriate (the + database configuration is done with environment variables, so pay attention to + ``local.env`` if it's important to you) +3. ``lando poweroff`` (defensively ensure no other Lando environments are running, probably not necessary, but a good habit) +4. ``lando rebuild`` +5. When you see the big "Boomshakala" message from Lando, you're ready to proceed +6. ``lando django-admin check`` will confirm the installation is working, and notify you of any misconfigurations +7. Revise your src/core/settings.py file as directed in the `Database Setup and Final Installation`_ instructions below +8. ``lando logs -f`` will show you the log output from Django, though when you're getting started, `lando django-admin check` will help you find configuration errors much faster than sifting through log file output +9. ``lando manage `` will send commands to the src/core/manage.py script, run `lando manage -h` to see more info +10. ``lando manage install_janeway`` will continue your installation of Janeway +11. ``lando manage test`` will run the Janeway unit test suite +12. ``lando python `` will send Python commands to the appserver +13. Browse to `http://localhost:8000` to see the site in action +14. run ``lando`` to see what other Lando tooling commands are available. + +Lando Tooling +------------- + +* ``lando psql`` Drops into the PostgreSQL client running on the database service +* ``lando db-import `` Imports a dump file into the database service +* ``lando ssh`` Drops into a shell on the application service, runs commands +* ``lando start`` Starts the Janeway app +* ``lando stop`` Stops the Janeway app +* ``lando rebuild`` Rebuilds the Janeway app +* ``lando restart`` Starts and stops the Janeway app, useful for forcing the app to use new configurations +* ``lando 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. + Manual Install -------------- diff --git a/docs/source/styling/image_guidelines.rst b/docs/source/styling/image_guidelines.rst index 4bcc914431..2800abd56d 100644 --- a/docs/source/styling/image_guidelines.rst +++ b/docs/source/styling/image_guidelines.rst @@ -1,8 +1,8 @@ Image guidelines ================ .. _imageguidelines: -This section describes the different images that can be uploaded in Janeway to customise the look and feel of your journal, -as well as the recommended sizes/aspec ratios for each of theme. + This section describes the different images that can be uploaded in Janeway to customise the look and feel of your journal, + as well as the recommended sizes/aspec ratios for each of theme. Header Image ------------------- diff --git a/etc/defaults.env b/etc/defaults.env new file mode 100644 index 0000000000..759b93aff7 --- /dev/null +++ b/etc/defaults.env @@ -0,0 +1,22 @@ +# DEFAULTS.ENV is a Docker .env file for configuring cores aspects of Janeway +# +# here are the Docker-Compose env file rules: https://docs.docker.com/compose/env-file/ +# here are the Lando env file rules: https://docs.lando.dev/config/env.html +# +# NOTE that Lando allows more than one env file to be used, which lets you +# override certain variables while leaving defaults in place. Consider using an +# override instead of modifying the defaults here. +# +# To override the defaults set below, copy the local.env.example file to +# local.env and then set the values in local.env appropriately. +# +############################################################################### +# Database + +DB_VENDOR=postgres +DB_NAME=janeway +DB_USER=postgres +DB_PASSWORD= +DB_HOST=db.janeway.internal +DB_PORT=5432 + diff --git a/etc/local.env.example b/etc/local.env.example new file mode 100644 index 0000000000..f006237b45 --- /dev/null +++ b/etc/local.env.example @@ -0,0 +1,22 @@ +# LOCAL.ENV is a Docker .env file for configuring cores aspects of Janeway +# +# here are the Docker-Compose env file rules: https://docs.docker.com/compose/env-file/ +# here are the Lando env file rules: https://docs.lando.dev/config/env.html +# +# NOTE that Lando allows more than one env file to be used, which lets you +# override certain variables while leaving defaults in place. Consider using an +# override instead of modifying the defaults here. +# +# To override the defaults set below, copy the local.env.example file to +# local.env and then set the values in local.env appropriately. +# +############################################################################### +# Database + +DB_VENDOR=postgres +DB_NAME=janeway +DB_USER=postgres +DB_PASSWORD= +DB_HOST=db.janeway.internal +DB_PORT=5432 + diff --git a/requirements.txt b/requirements.txt index eb508949ce..4e2e373c11 100644 --- a/requirements.txt +++ b/requirements.txt @@ -31,7 +31,6 @@ mock mysqlclient==1.3.12 pdfkit Pillow==6.2.0 -psycopg2 psycopg2-binary pyasn1==0.1.9 pycparser==2.14