Skip to content

Installation

Jump to bottom
Ryan Hodges edited this page Oct 27, 2025 · 20 revisions

Installation on Ubuntu 22.04+

For Local Development (from Windows, Mac, or Linux):

It is recommended that you do any development in a VM -- this will also solve for developing on an operating system that is NOT Ubuntu. The maintainers of this repo prefer to use Vagrant to bootstrap creating the VM. You will find a Vagrantfile in this repo.

  • Install Vagrant
  • Modify the Vagrant file to fit your needs
    • Depending on your host OS, look to keep your edits inside of the relevant Windows, Mac, or Linux section.
  • Pay close attention to the config.vm.synced_folder, and be sure they match the next section on Cloning the code!

Once you code is cloned (below) and you Vagrantfile is configured, run vagrant up to turn your VM on, then vagrant ssh to connect to your VM's command line.

WARNING

At the time of this writing, the Vagrantfile creates /usr/local/apps/madrona_portal/ on your VM guest, instead of "madrona-portal" (as is on your VM host). Please adjust your Vagrantfile or your commands (after 'Cloning the code') and remember this difference when debugging any issues. There may also be references to the companion apps being installed to /usr/local/apps/madrona-apps rather than the apps directory in your madrona-portal module. It is recommended you adjust your Vagrantfile as necessary.

Setting up your new VM

If you are not using Vagrant, or you don't have a local copy of madrona-portal synced to load at /usr/local/apps/madrona-portal, run sudo mkdir /usr/local/apps/ first.

cd /usr/local/apps
sudo chown vagrant ./

Install Dependencies

sudo apt update
sudo apt upgrade -y

sudo apt install git postgresql postgresql-contrib postgis libjpeg-dev redis-server python3-venv python3-pip libgdal-dev gdal-bin python3-gdal -y

Ubuntu 22.04 (Jammy)

sudo apt install postgresql-server-dev-14 -y

Ubuntu 24.04 (Noble)

sudo apt install postgresql-server-dev-16 -y

Cloning the code

For the purposes of this installation guide, we will be placing this madrona-portal module in

  • /usr/local/apps/ And we will be cloning all of the required dependency modules in
  • /usr/local/apps/madrona-portal/apps
mkdir /usr/local/apps/
cd /usr/local/apps
git clone https://github.com/Ecotrust/madrona-portal.git
cd madrona-portal/apps/
git clone https://github.com/Ecotrust/django_url_shortener.git
git clone https://github.com/Ecotrust/madrona-analysistools.git
git clone https://github.com/Ecotrust/madrona-features.git
git clone https://github.com/Ecotrust/madrona-manipulators.git
git clone https://github.com/Ecotrust/madrona-scenarios.git
git clone https://github.com/Ecotrust/mp-map-groups.git
git clone https://github.com/Ecotrust/mp-accounts.git
git clone https://github.com/Ecotrust/mp-data-manager.git
git clone https://github.com/Ecotrust/mp-drawing.git
git clone https://github.com/Ecotrust/mp-explore.git
git clone https://github.com/Ecotrust/mp-layers.git
git clone https://github.com/Ecotrust/mp-proxy.git
git clone https://github.com/Ecotrust/mp-visualize.git
git clone https://github.com/Ecotrust/p97-nursery.git

Then, depending on if you want to install a pre-configured instance, grab the appropriate module:

  • mida-portal: Mid-Atlantic Regional Council on the Ocean (MARCO) Ocean Data Portal
  • wcoa: West Coast Ocean Alliance (WCOA) Ocean Data Portal
  • wc-offshore-portal: OROWindMap
git clone https://github.com/Ecotrust/mida-portal.git
git clone https://github.com/Ecotrust/wcoa.git
git clone https://github.com/Ecotrust/wc-offshore-portal.git

Python Virtual Environment

It is recommended you use a Python Virtual Environment to encapsulate all of the python dependencies

If installing a dev environment on a local VM

IT IS VERY IMPORTANT THAT THE env/ DIRECTORY IS NOT SHARED WITH YOUR HOST. There will be a LOT of permissions problems if you ever need to update your libraries. Instead, store them just before the shared directories:

cd /usr/local/apps/
python3 -m venv env
source /usr/local/apps/env/bin/activate

Else:

cd /usr/local/apps/madrona-portal/
python3 -m venv env
source /usr/local/apps/madrona-portal/env/bin/activate

Libraries

Install the required stack from requirements.txt

pip install -r /usr/local/apps/madrona-portal/requirements.txt

Then, install your Madrona companion modules:

pip install -e /usr/local/apps/madrona-portal/apps/django_url_shortener/url_short/
pip install -e /usr/local/apps/madrona-portal/apps/madrona-analysistools/
pip install -e /usr/local/apps/madrona-portal/apps/madrona-features/
pip install -e /usr/local/apps/madrona-portal/apps/madrona-manipulators/
pip install -e /usr/local/apps/madrona-portal/apps/madrona-scenarios/
pip install -e /usr/local/apps/madrona-portal/apps/mp-map-groups/
pip install -e /usr/local/apps/madrona-portal/apps/mp-accounts/
pip install -e /usr/local/apps/madrona-portal/apps/mp-data-manager/
pip install -e /usr/local/apps/madrona-portal/apps/mp-layers/
pip install -e /usr/local/apps/madrona-portal/apps/mp-drawing/
pip install -e /usr/local/apps/madrona-portal/apps/mp-explore/
pip install -e /usr/local/apps/madrona-portal/apps/mp-proxy/
pip install -e /usr/local/apps/madrona-portal/apps/mp-visualize/
pip install -e /usr/local/apps/madrona-portal/apps/p97-nursery/

Next, install your preconfigured Madrona-Portal project, if you cloned one:

pip install -e /usr/local/apps/madrona-portal/apps/mida-portal/
pip install -e /usr/local/apps/madrona-portal/apps/wcoa/
pip install -e /usr/local/apps/madrona-portal/apps/wc-offshore-portal/

Install GDAL for Python:

For Ubuntu 22.04 and below:

pip uninstall numpy
gdal-config --version

Based on the result of that last command, you will get a version number like 3.4.1. Attempt to install the largest version of pygdal that does not push past this minor version, for example:

pip install "pygdal<3.4.2" --no-cache-dir

For Ubuntu 24.04+

pip install "GDAL==$(gdal-config --version)" --no-cache-dir

Create Database

Choose an appropriate database name and primary username. In the commands below, replace the following values with your own:

  • Database Name: <DBNAME>
  • Database User Name: <DBUSER>
  • Database User Password: <DBPASSWORD>
  • You will NOT use < or > around your names below.

Production Installs

Create your user, your database, and initialize the DB for postgis. After the first command, you will be prompted to provide <DBPASSWORD>

sudo -u postgres createuser -s -P <DBUSER>
sudo -u postgres createdb -O <DBUSER> <DBNAME>
sudo -u postgres psql -c "CREATE EXTENSION postgis; CREATE EXTENSION postgis_topology;" <DBNAME>

Update Database User Privileges

Depending on whether you installed PostgreSQL v14 (for Ubuntu 22.04) or v16 (24.04), adjust the version number below accordingly:

sudo vim /etc/postgresql/16/main/pg_hba.conf

Edit the file near the bottom (section # "local" if for Unix domain socket connections only) so that you have a line like:

local    <DBNAME>     <DBUSER>                            password

Development Installs (cheater path)

When security isn't a huge issue, we can just use PostgreSQL's built-in postgres user You will still need to think up a good <DBNAME>, though:

sudo -u postgres createdb -O postgres <DBNAME>
sudo -u postgres psql -c "CREATE EXTENSION postgis; CREATE EXTENSION postgis_topology;" <DBNAME>

Update Database User Privileges

Depending on whether you installed PostgreSQL v14 (for Ubuntu 22.04) or v16 (24.04), adjust the version number below accordingly:

sudo vim /etc/postgresql/16/main/pg_hba.conf

Edit the line below # Database administrative login by Unix domain socket so that postgres user uses the trust METHOD:

local    all     postgres                            trust

Restart PostgreSQL Service

sudo service postgresql restart

Migrating old .sql in (if rebuilding from old data)

sudo -u postgres psql <DBNAME> < ./path/to/SQL/file.sql

Configure Django Settings

Create your static and media folders: 'media' will hold files uploaded via your app from users and administrators. 'static' will be used on production servers to aggregate all javascript, css, images, and other static files into one place so that an application server can serve them.

mkdir /usr/local/apps/madrona_portal_media
mkdir /usr/local/apps/madrona_portal_static

Create your settings file:

  1. Copy the file ./madrona-portal/marco/config.ini.template to ./madrona-portal/marco/config.ini (drop .template)

  2. [APP]

    1. if you are deploying to a production server, set DEBUG = False
    2. Replace SECRET_KEY by mashing a bunch of gibberish in
    3. modify MEDIA_ROOT to point to your media folder: MEDIA_ROOT = /usr/local/apps/madrona_portal_media
    4. modify STATIC_CORE to point to your static folder: STATIC_CORE = /usr/local/apps/madrona_portal_static
    5. ensure STATIC_ROOTpoints at madrona's static dir: STATIC_ROOT = /usr/local/apps/madrona-portal/marco/static
    6. If you have these values, plug in your keys for Google Analytics (GA_ACCOUNT) and RECAPTCHA...

  3. [DATABASE]

    • USER = <DBUSER>
    • NAME = <DBNAME>
    • PASSWORD = <DBPASSWORD> <-- not needed for development using 'postgres' user

  4. Many of the other values will work as is, but some are dummy content that you should correct to match your use-case

    • A separate document reviewing the settings for Madrona Portal is in the works

If you are using an existing project, be sure to capture that under [APP]:

  • For MARCO:
PROJECT_APP = mida
PROJECT_SETTINGS_FILE = True
  • For WCOA:
PROJECT_APP = wcoa
PROJECT_SETTINGS_FILE = True
  • For OROWindMap:
PROJECT_APP = offshore
PROJECT_SETTINGS_FILE = True

Initial Data

TODO.

Final Organization

Ensure that you have your python virtual environment activated and then cd /usr/local/apps/madrona-portal/marco. You should be next to a file called manage.py

python3 manage.py makemigrations
python3 manage.py migrate
python3 manage.py collectstatic
python3 manage.py compress --force

You should now be set up to run your site.

If you are doing this on a local development machine, you should be able to run the following (if settings DEBUG=True):

python3 manage.py runserver 0.0.0.0:8000

You should now be able to see your site at http://localhost:8000/

Clone this wiki locally