After setting up the prerequisites, run the following commands from the uipa
directory in the working directory that you cloned the UIPA repository into.
- In a terminal window, run
docker-compose up
. - In another terminal window, run
bash data/seed/init_db.sh
. - In that same terminal window, run
python manage.py runserver
. - Open
http://127.0.0.1:8000/
in your web browser.
There are three main parts for developing UIPA.
- The Database and Search Engine (Elasticsearch & PostgreSQL)
- The Backend (Django web server)
- The Frontend (ViteJS; pronounced like "veet")
Clone the UIPA repository to a working directory and change to the uipa
directory created in your working directory.
git clone https://github.com/CodeWithAloha/uipa
cd uipa
For the purposes of this guide, you'll be running commands from this uipa
directory.
Make sure that you have these installed:
-
Docker Desktop (for the database and search engine)
-
Python 3.10 (for the backend server)
Note: You can use pyenv to manage your Python versions.
-
PostgreSQL
psql
command line client (for Django admindbshell
support)Note: Comes with a full PostgreSQL installation.
-
GDAL (Geospatial Data Abstraction Library) (GIS support for PostgreSQL)
Note: You may need to set the GDAL_LIBRARY_PATH and/or GEOS_LIBRARY_PATH environment variables in your shell environment. Remember to add export in front of the variable.
-
[ImageMagick] (https://formulae.brew.sh/formula/imagemagick)
Note: You may need to set the MAGICK_HOME environment variables in your shell environment. Remember to add export in front of the variable.
-
NodeJS & npm (for the frontend)
-
Yarn (for the frontend)
Do this once to get things ready to run the parts to develop UIPA.
The database and search engine are run together with one command using the provided docker-compose.yml
file.
The first time that you run the command, it will build the required Docker images before running the Docker containers in your Docker Desktop.
After running docker-compose up
successfully, the output in your terminal should look something like:
Type a Ctl-C
(hold control key down and type the C
key) to stop the docker-compose
command.
Run these commands:
yarn install
yarn build
These commands do the following:
- Install ViteJS frontend JavaScript tooling.
- Install JavaScript dependencies.
- Build the frontend assets (JavaScript and CSS) for the development server.
This assumes that your Python 3.10 installation is run with the python
command. If your installation requires you to use python3
instead, use that.
We're using a Python virtual environment created using the standard venv
module. This isolates the dependencies for UIPA from any other Python work or project that you might have. In other words, it minimizes damage that might be caused from working with UIPA.
Run these commands:
-
python -m venv venv
-
source venv/bin/activate
-
pip install -r requirements.txt
-
bash data/seed/init_db.sh
You will be prompted for the email address, username, and password for an administrative user. You can use this or pick your own:Email address: admin@uipa.org Username: admin Password: secret007
-
python manage.py check
These commands do the following:
- Set up a Python virtual environment in the working directory.
- Activate that Python virtual environment.
- Install the needed Python packages in the active Python virtual environment.
- Initialize the database.
- Create the search engine's indexes.
- Create an administrative user.
- Check that your Django development environment is set up correctly.
If you don't have it running in a termial window, start the database and search engine using docker-compose up
.
In another terminal window, run the Django development web server using python manage.py runserver
.
After starting the development web server, you should see something like this in your terminal:
At this point, you'll have at least two open terminal windows with servers running in them.
To stop the servers, type a Ctl-C
(hold control key down and type the C
key) in each terminal window running a server.
Visit http://127.0.0.1:8000/ in your browser and you should see something like:
The set up for the frontend created the assets that are needed for the development website to work without running the ViteJS
frontend server. Also, the Dev
configuration set in the manage.py
file arranges things to use the created assets.
When you want to make changes to the JavaScript or CSS styling, then you'll need to switch to using the ViteJS
frontend server.
To run the frontend server, you'll need to change the configuration for the backend. Do the following:
- Stop the backend server.
- Edit the
Dev
configuration inuipa_org/settings/development.py
and comment out this line by inserting a '#' before it:FRONTEND_DEBUG = False
- Restart the backend server.
In another terminal window, run yarn run serve
.
When running the frontend server, you'll have three terminal windows open. One each for the database/search engine, backend, and frontend.
To stop the servers, type a Ctl-C
(hold control key down and type the C
key) in each terminal window running a server.
The source for the frontend assets are found in the frontend
directory.