- Install Python 3 (https://www.python.org), and make sure that Python is added to your PATH variable.
- Working from your root projects directory (e.g.,
~/my_projects
), create python virtual environment:python -m venv dm_apps_venv
- Activate the virtual environment:
.\dm_apps_venv\Scripts\activate
(Windows) ORsource ./dm_apps_venv/bin/activate
(Linux) - Clone project:
git clone https://github.com/dfo-mar-odis/dm_apps
- navigate into the project directory:
cd dm_apps
- Install the Python packages required by the DM APPS application:
pip install -r requirements.txt
- If you get an error when installing this, you will have to open the requirements.txt and comment out the lines for
mysqlclient
andshapely
. - Rerun the package installation line above
- You will have to download a precompiled version of
mysqlclient
andshapely
. The binary versions of these packages are available here:- mysqlclient. Be sure to select the file that matches your system configuration.
- shapely. Be sure to select the file that matches your system configuration.
- So, for example, if your a running python 3.6 on an AMD64 processor, you would download the file called 'mysqlclient‑1.x.x‑cp36‑cp36m‑win_amd64.whl.'. If you do not select the correct file version, it will not work.
- Once you have downloaded the files, you can install them as follows:
pip install /path/to/local/file/mysqlclient‑1.x.x‑cp36‑cp36m‑win_amd64.whl
pip install /path/to/local/file/shapely‑1.x.x‑cp36‑cp36m‑win_amd64.whl
- Do not forget to uncomment the two lines from the requirements.txt file
- If you get an error when installing this, you will have to open the requirements.txt and comment out the lines for
- If you are using a local Sqlite database (i.e. this is the default configuration),
be sure to run migrations before you get started:
python manage.py migrate
. - Change directory to the root
dm_apps
folder (if not already there) and run the development server:python manage.py runserver
Before proceeding any further, make sure you have completed the steps outlined above.
- to create a superuser, use the following command
python manage.py createsuperuser
- please note that all usernames in this project should be an email address. Otherwise you will have trouble logging in through the login page.
- To import some of the basic reference tables, please use the follow command in windows:
import_fixtures.bat
NOTE: For linux users, sorry, we don't have a script yet. You will have to import the fixtures manually usingpython manage.py loaddata my_fixture.json
.
We are attempting to build this project in a modular fashion that will allow flexible implementation of the application. The idea is that there might be multiple instances of this app in production and each instance will want to have its own custom settings, for example, which database it is connecting to, which apps are connected, allowed hostnames, etc...
Without any customizations, the site will connect to a local sqlite3 database. This is an ideal, fast and simple option for local development.
After running the migrate
command an empty sqlite database will be created in the project root called db.sqlite3
.
This file is already in the .gitignore file.
Static files are not stored in the git repository, they can be pushed to the static file server using python manage.py findstatic
and downloaded to a machine for local development using python manage.py collectstatic
. If this step is skipped the "you are not using chrome" warning message will show and images will appear broken on the "127.0.0.1:8000/en" page
The first step of customizing the site's configuration is by cloning the .env_sample
file and renaming this copy to .env
. This file is also in the .gitignore.
This file has numerous switches and flags that can be used for customizing the application. The .env_sample
file has a lot of annotation and the configuration
settings should be fairly straight-forward. If you find any of them confusing, please open an issuein the dmapps
repo.
Most types of customizations can be done through the .env
file. However, changes made to which apps are switched on/off or which type of database backend you want to
use must be done in a separate file. To do these types of customization, make a copy of the file called ./dm_apps/default_conf.py
to ./dm_apps/my_conf.py
.
The latter file is in the .gitignore therefore none of the changes made will be recorded to the repo. If the my_conf.py
file is present when the
application boots up, the default_conf.py
file will be ignored and the application will look to the my_conf
file. At this point you would be free
to make any changes you like to the my_conf
.
If you are connecting to a mysql database, you do not need to make a custom my_conf
. Instead simply provide the database credentials in the .env
.
Important: You should not be making changes to the .env_sample
and/or default_conf.py
unless these are changes that are meant to be
persist in the repository for all users. For example, if you were working on a new app, you would eventually have to modify the default_conf
.
Apps can be easily connected and disconnected from an instance of the application. To do so, you simply comment / uncomment
the app of interest in the app dictionary: my_conf.APP_DICT
. Each connected app should have a card display on the site's main index page.
- If you are reading this, your contributions and collaborations are welcomed :)
- Please do your work locally and make sure to pull regularly from
origin/master
- When ready to merge your work, please be sure to run the project's unit tests before creating your merge request
- if you are using windows, you can run the suite of test using the following batch file:
run_tests_in_windows.bat
- if you are using windows, you can run the suite of test using the following batch file:
- Please do not create a merge request that has conflicts with the master branch, unless you specifically need help with dealing with any conflicting code.
- in the case of the latter, please be sure to properly assign your merge request and add the appropriate comments