The client and server code for the web platform on https://climateconnect.earth.
Climate Connect depends on PostgreSQL/PostGIS and Redis.
We use Python/Django for our backend and Next.js for the frontend.
Note: we use Python 3, so for all instructions we assume python
means python3
.
First, clone the GitHub repository
git clone https://github.com/climateconnect/climateconnect
VSCode Dev Containers allow deploying a development environment including using Docker independent of the host operating system or installed programs.
Make sure you have the Remote Development Extension Pack VSCode extension installed.
-
Open the repo in VS Code
-
Start Docker (if it's not running)
-
Run the command "Reopen in Container"
-
Wait for it to be done setting up the Dev Container and running the setup scripts. This will take 1-5 minutes the first time and 10 seconds after that. It should look something like this:
-
Start the frontend dev server using
cd frontend && yarn dev
-
Start the backend server using
cd backend && make start
. If you get a "Django is not installed" error runCtrl+Shift+P
(orCmd+Shift+P
) "Select Python interpreter" -> Recommended so it uses the Python venv.
You can get a Redis REPL using redis-cli -h redis
and a PostgreSQL REPL using psql
.
If you can't or don't want to use VS Code dev containers, follow the steps below.
- Create a local Postgres database with your own username and password. E.g.,
createdb climateconnect-dev
. - Install PostGIS on your local machine.
- Create the PostGIS extension within that database: run
CREATE EXTENSION postgis;
.
You will connect to this for your local backend project.
- Create a new superuser
- Alter your new user's password
- Create a new database
Supply these values to your local backend/.backend_env
.
We use Docker to run the local Redis server. See the Docker install docs if you don't have it.
Make sure to install docker-ce, docker-ce-cli, containerd.io, and docker-compose.
Run ./install_deps.sh
to install the JavaScript dependencies and the Python dependencies in a virtualenv.
- Go to backend directory:
cd backend
- Run
make install
to install all backend libraries. - Create
.backend_env
to set environment variables.- You can find up-to-date sample env variables in
backend/local-env-setup.md
. - For the Django
SECRET_KEY
, runopenssl rand -base64 32
to create a 32 char random secret.
- You can find up-to-date sample env variables in
- Run
make migrate
to run Django migrations.- Note: This command is used for when you first start, or whenever you are adding or updating database models.
- Create a superuser using
python manage.py createsuperuser
- You can then access your admin panel via <API_URL>/admin/
- Ensure Docker is running and then run
sudo docker-compose up
. This will start a Redis server on Docker. - Ensure the Postgres server is running.
- Run server using
make start
. - Run Celery using
celery -A climateconnect_main worker -l INFO
If test data is needed, run
python manage.py create_test_data --number_of_rows 4
If you need to wipe your local database and start over, run
sudo -u postgres psql # note this might differ slightly in name based on your postgres setup
And then at the psql
prompt,
postgres-# \list
to show available databases. Once you've identified the Climate Connect database name (e.g. we'll call it $DATABASE_NAME
), you can,
postgres-# \connect $DATABASE_NAME
$DATABASE_NAME-# \dt
$DATABASE_NAME-# DROP SCHEMA public CASCADE;
$DATABASE_NAME-# CREATE SCHEMA public;
$DATABASE_NAME-# \q
Then run
make migrate
to update your migrations, and
python manage.py createsuperuser
to re-create a super user to be used in the Django admin panel.
For unit tests, to run the test suite use:
make test
Or a specific test file or test class:
python manage.py test <file_path> or <file_path + class_name>
For linting, we use flake8. Lint with
make lint
For formatting, we use Black. Format a specific file with
make format path_to_file
or a directory with
make format directory
More configuration for Black can be found in the pyproject.toml
file.
cd frontend
.yarn
to download all npm packages.- Add a
.env
file for frontend environment variables. You can find variables you need to set in/frontend/next.config.js/
For local development, use the following for .env
:
API_HOST="localhost"
API_URL="http://127.0.0.1:8000"
BASE_URL_HOST="localhost"
SOCKET_URL="ws://localhost"
ENVIRONMENT="development"
Note: This is for people who are using newer version of node (v17.0.1) or have new apple M1 devices. Before running yarn dev
, please run this command export NODE_OPTIONS=--openssl-legacy-provider
. You can save this in your ~/.zshrc
file as well.
And finally yarn dev
to spin up the Next.js app! Check out our frontend (FE) code style guidelines wiki to follow codebase best practices and contribute to a healthy and maintainable codebase.
For unit tests, we use Jest. Write test files with .test.js
and execute them directly with
yarn jest path/to/testfile.test.js
For linting, we use eslint
. Watch files to fix lint issues with
yarn lint:watch
For formatting, we use prettier
. Format with
yarn format
See npm scripts in package.json
for more.
You can analyze size of the (frontend) bundle with
yarn analyze-bundle
Currently the project is utilizing credits to deploy onto Azure. That deployment utilizes the two scripts in the root of the project, start_backend.sh
and start_frontend.sh
.
- Use GitHub actions to push to a server. A deploy file can be found in
.github/workflows
cd frontend
yarn --production
yarn build
node server.js
ORnext start
- Make sure your
ENVIRONMENT
env variable is set toproduction
when deploying to the production server - Follow steps 1-5 of the "Getting started locally - backend" (above in this file)