Pyregence

A web portal for displaying near-term fire forecast results for the state of California.
https://github.com/pyregence/pyregence

Category: Biosphere
Sub Category: Wildfire

Last synced: about 1 hour ago
JSON representation

Repository metadata

The main web portal for the Pyregence project.

• Host: GitHub
• URL: https://github.com/pyregence/pyregence
• Owner: pyregence
• License: epl-2.0
• Created: 2020-03-11T13:56:31.000Z (about 6 years ago)
• Default Branch: main
• Last Pushed: 2026-04-15T19:30:01.000Z (4 days ago)
• Last Synced: 2026-04-16T01:02:30.003Z (4 days ago)
• Language: Clojure
• Homepage: https://pyrecast.org
• Size: 20.7 MB
• Stars: 6
• Watchers: 3
• Forks: 0
• Open Issues: 5
• Releases: 29
• Metadata Files:
  • Readme: README.org
  • License: LICENSE.txt

README.org

          * Pyregence

Pyregence is a web portal for displaying near-term fire forecast
results for the state of California. The fire spread and impact maps
are generated by running multiple state-of-the-art simulation models
on a continuously updated stream of weather data.

At this time, Pyregence displays results from these open-source fire
behavior models:

1. [[https://github.com/lautenberger/elmfire][ELMFIRE]]
2. [[https://github.com/pyregence/gridfire][GridFire]]

** Installation

To run PyreCast locally you will need a JDK ([[https://openjdk.org/projects/jdk/21/][OpenJDK-21]]),
Clojure ([[https://clojure.org/guides/install_clojure][cli-1.11.*]]), [[https://github.com/babashka/babashka#installation][babashka]],
NPM ([[https://nodejs.org/en/download][node-22]]), and PostgresSQL ([[https://www.postgresql.org/download][13]]).
You can install these packages globally on your system or, assuming you have
[[https://guix.gnu.org/][guix]] installed, by running [[./pyregence-shell.sh][pyregence-shell.sh]]
which creates a container shell with all of the necessary packages installed into it.
For the current package list see [[./manifest.scm][manifest.scm]].

** Application Configuration

On startup, the Pyregence application reads a file called ~config.edn~
in the top-level directory of this repository, which contains various
user-configurable system parameters. A sample file called
~config.default.edn~ is provided with this repository to get you
started. To begin, simply rename (or copy) it to ~config.edn~. Then edit
it according to the following sections.

Please note that you must replace all values surrounded with angle
brackets (e.g., "") with actual values for the application to
work correctly. The Mapbox ~:access-token~ field requires a
[[https://docs.mapbox.com/help/getting-started/access-tokens/][Mapbox access token]].
The ~:wildfire-camera-api-key~ field requires an API key for the
[[https://www.alertwildfire.org/][AlertWildfire]] API. You should change the
~:pyr-auth-token~ field to a unique string that's at least 16 characters long.

** PostgreSQL Database Setup

*PostgreSQL* needs to be installed on the machine that will be hosting
the Pyregence website. Once the PostgreSQL database server is running
on your machine, you should navigate to the top-level directory and run
the database build command as follows:

#+begin_src sh
clojure -M:build-db build-all [--dev-data]
#+end_src

This will begin by creating a new database and role called *pyregence*
and then add the pgcrypto and postgis extensions to it. Next, the
script will populate the database with the schemas, tables, and
functions that are necessary for storing and processing Pyregence's
data. Finally, it will load some default data into these tables that
is necessary for the website to function properly. You can optionally load
dev data with ~--dev-data~. This will initialize the DB with 2 users and a
"Development" organization.

*** Performance Settings

If you want to improve the performance of your PostgreSQL server, one
way is to visit the [[https://pgtune.leopard.in.ua/][pgtune]] website
and input your system settings. This will generate a set of configuration
options that you can add to the ~postgresql.conf~ file in your system-specific
PostgreSQL data directory.

If you would like to keep these settings separate for your own
reference, you can add them to a file called "performance.conf" that
you should place in your PostgreSQL data directory. You can then
import these settings into ~postgresql.conf~ by adding this line to the
end of that file:

#+begin_example
include = 'performance.conf'
#+end_example

Note that the PostgreSQL server will need to be restarted for these
changes to take effect.

** Environment Variable Setup

In order for your command-line shell to find the programs installed
above, you will need to update your environment variables. Under
GNU/Linux, *BSD, or MacOS X, you can set these through your shell's
.*rc or .*profile configuration files in your $HOME directory. In a
Windows environment, you will need to set either the USER (for the
current user only) or SYSTEM (for any user) environment variables
under your system settings menu.

*** Step 1: Add JAVA_HOME

On a Unix machine using bash (e.g., GNU/Linux or MacOS X):

#+begin_src sh
export JAVA_HOME=
#+end_src

On a Unix machine using csh or tcsh (e.g., *BSD):

#+begin_src sh
setenv JAVA_HOME 
#+end_src

On a Windows machine:

#+begin_example
JAVA_HOME = C:\Program Files\Java\jdk-X.X.X
#+end_example

Replace *X.X.X* with the JDK version installed on your computer.

*** Step 2: Update PATH

On a Unix machine using bash (e.g., GNU/Linux or MacOS X):

#+begin_src sh
export PATH=$PATH:$JAVA_HOME/bin
#+end_src

On a Unix machine using csh or tcsh (e.g., *BSD):

#+begin_src sh
setenv PATH $PATH\:$JAVA_HOME/bin
#+end_src

On a Windows machine, add these entries to the PATH environment
variable:

#+begin_example
%JAVA_HOME%\bin
C:\Program Files\PostgreSQL\X\lib
C:\Program Files\PostgreSQL\X\bin
#+end_example

Replace *X* with the PostgreSQL version installed on your computer.

** Development Web Server

*** Modifying hosts file

Add the following line to your hosts file. This local URL should be used for
local developing in place of ~localhost~ due to CORS settings on the GeoServer
instances used in Pyrecast.

#+begin_example
127.0.0.1 local.pyrecast.org
#+end_example

*** Updating Chrome HSTS Settings

If you are planning on doing your local development on Chrome, you'll need to
update your HSTS (HTTP Strict Transport Security) settings so that trying to
hit ~http://local.pyrecast.org~ doesn't automatically redirect to
~https://local.pyrecast.org~. To do so, open chrome://net-internals/#hsts in your
Chrome browser and scroll down to the "Delete domain security policies" section.
Enter ~local.pyrecast.org~ in the box and click "Delete". You should now be all
set to hit ~http://local.pyrecast.org~. If you're still running into issues,
try clearing your Chrome browser cache (visit chrome://settings/privacy and
click "Clear browsing data").

*** Launching Figwheel

To start the Figwheel server, navigate to the top-level project
directory and run:

#+begin_src sh
clojure -M:default-ssl-opts:figwheel
#+end_src

This will start a web server on ~http://local.pyrecast.org:8080~ (also
accessible from ~http://localhost:8080~), which serves up the website in
dev mode. Any changes to CLJS files will be automatically pushed to
the browser when the files are saved. Any changes to CLJ files will be
pushed to the running server process. A CLJS browser REPL will also be
launched at the terminal for you to interactively develop your
client-side code.

*** Checking for Reflection Warnings

From the top-level project directory run:

#+begin_src sh
clojure -M:check-reflection
#+end_src

This will emit warnings when reflection is needed to resolve Java
method calls or field accesses. To resolve any that appear, add
[[https://clojure.org/reference/java_interop#typehints][type hints]] to your code. Resolving all reflection warnings can improve
system performance.

*** Debugging Your Dev Environment

If your dev environment isn't working properly, refer to the following
list of things to double-check:

1. Make sure you have all of the required installation requirements listed above. For example, calling ~java --version~ should yield:

#+begin_src
openjdk 17.0.3 2022-04-19
OpenJDK Runtime Environment (build 17.0.3+7-Ubuntu-0ubuntu0.20.04.1)
OpenJDK 64-Bit Server VM (build 17.0.3+7-Ubuntu-0ubuntu0.20.04.1, mixed mode, sharing)
#+end_src

2. Make sure your ~config.edn~ file has every field from ~config.default.edn~ and you've correctly updated the fields that need updating (e.g. the access tokens are correct).

3. Make sure your local database is working properly. To get a fresh database (with the development data) run:

#+begin_src sh
clojure -M:build-db functions
clojure -M:build-db build-all --dev-data
#+end_src

4. Make sure your ~/etc/hosts~ file has a line for ~127.0.0.1 local.pyrecast.org~ and that you're hitting ~http://local.pyrecast.org:8080~ (make sure the port matches up to whatever you've set in ~config.edn~) in your web browser.

If none of the above fix your problem, you should look at your Figwheel
console and web browser dev tools console after running ~clojure -M:default-ssl-opts:figwheel~
for more information.

** Production Web Server

*** Installation Requirements

- [[https://certbot.eff.org/][certbot]]
- [[https://www.openssl.org/source/][openssl]]

*** Enabling HTTPS

View the [[https://github.com/sig-gis/triangulum#triangulumhttps][Triangulum HTTPS]]
page for further instructions on enabling HTTPS.

*** Compiling ClojureScript to JavaScript

To compile the ClojureScript files under src/cljs to JavaScript under
`target/public/cljs`, navigate to the top-level project directory and
run:

#+begin_src sh
clojure -M:compile-cljs
#+end_src

The main JavaScript entry point file will be written to
`target/public/cljs/app.js`. The ClojureScript compiler options are read
from the top-level `compile-prod.cljs.edn` file.

*** Launching the Web Server

To compile and run the web application, navigate to the top-level
project directory and run:

#+begin_src sh
clojure -M:build-db functions
clojure -M:default-ssl-opts:server start -m [dev|prod] [-p 8080] [-P 8443] [-r/--repl]
#+end_src

The website will then be available at ~http://localhost:8080~ unless a
port is specified. An http port can be specified with -p and an https
port can be specified with -P. In dev mode, server-side exceptions
will be displayed in the browser and Clojure source files will be
reloaded whenever you refresh the page. These features are disabled in
prod mode. If -m is unspecified, it will default to prod mode.

If the ~-r/--repl~ flag is provided, then a repl server will start on port 5555.
This can be connected to for debugging or managing the server.

The server is also configurable using the ~config.edn~ file:
#+begin_src clojure
;; config.edn
{:server {:http-port  8080
          :https-port 8443
          :mode       ""
          :log-dir    "logs"
          :repl       }}
#+end_src

If you don't already have an SSL certificate, you cannot specify an
https port.

*** Running the Web Server as a System Service

View the [[https://github.com/sig-gis/triangulum#triangulumsystemd][Triangulum Systemd]]
page for further instructions on enabling the app as a system service.

*** Maintaining Daily Logs

By default the server will log to standard out. If you would like to
have the system log to ~YYYY-DD-MM.log~, use the `-o path` option to
specify an output path. You can either specify a path relative to
the top-level directory of this repository or an absolute path on
your filesystem. The logger will keep the 10 most recent logs.

*** Running https via nginx (optional)

**** Install required packages

- [[https://nginx.org/en/][nginx]]

**** Copy the nginx template and update

Ubuntu example:

#+begin_src sh
sudo cp nginx/nginx-template.conf /etc/nginx/sites-available/pyregence.conf
sudo ln -s /etc/nginx/sites-available/pyregence.conf /etc/nginx/sites-enabled/
sudo nano /etc/nginx/sites-available/pyregence.conf
sudo service nginx restart
#+end_src

**** Alternative server deployment

When using nginx, run the server in http mode only. If multiple servers are
running on the same VM, be sure to assign them different ports. Remember that
nginx needs port 8080, which is the default port for the server deployment.
Instead deploy with a non default port:

#+begin_src sh
clojure -M:run-server -p 8081
#+end_src

For HTTPS, each server does not need its own deploy hook. Instead nginx needs
a single deploy hook:

#+begin_src sh
sudo nano /etc/letsencrypt/renewal-hooks/deploy/nginx.sh
#+end_src

Add ~systemctl reload nginx~ to the file and save.

#+begin_src sh
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/nginx.sh
#+end_src

**** Diagnose errors with nginx by looking in the log

Ubuntu example:

#+begin_src sh
sudo less +G /var/log/nginx/error.log
#+end_src

*** JAR

To build a JAR run:

#+begin_src sh
clj -X:build-uberjar
#+end_src

Or if you have Guix installed, run:

#+begin_src sh
./pyregence-shell.sh -- clojure -X:build-uberjar
#+end_src

This will produce a uberJAR located at  target/pyregence---standalone.jar which depends only
on a config.edn, java and psql. The JAR's cli actions are available through ~java -jar~:

#+begin_src sh :results raw
java -jar target/pyregence-*
#+end_src

The current notable actions are [[https://github.com/sig-gis/triangulum?tab=readme-ov-file#triangulumserver][running the server]] and the [[https://github.com/sig-gis/triangulum?tab=readme-ov-file#triangulumbuild-db][building the database]].

** Vulerability checking
To check for vulerabilities in this project, use ~clojure -M:clj-watson scan -p deps-for-clj-watson.edn -s~

** Other Documentation

- [[file:docs/pyrecast-architecture.md][Pyrecast Architecture]]
- [[file:docs/pyrecast-back-end.md][Pyrecast Back-End]]

** License and Distribution

Copyright © 2020-2026 Spatial Informatics Group, LLC.

Pyregence is distributed by Spatial Informatics Group, LLC. under the
terms of the Eclipse Public License version 2.0 (EPLv2). See
~LICENSE.txt~ in this directory for more information.

        

---

Owner metadata

• Name: pyregence.org
• Login: pyregence
• Email: dssaah@usfca.edu
• Kind: organization
• Description: EPIC: Open Fire Modeling Environment
• Website: https://pyregence.org
• Location: San Francisco, CA USA
• Twitter:
• Company:
• Icon url: https://avatars.githubusercontent.com/u/61761393?v=4
• Repositories: 1
• Last ynced at: 2023-06-28T20:27:20.472Z
• Profile URL: https://github.com/pyregence

---

GitHub Events

Total

• Create event: 152
• Commit comment event: 1
• Release event: 7
• Delete event: 121
• Pull request event: 155
• Fork event: 1
• Issues event: 2
• Watch event: 5
• Issue comment event: 148
• Push event: 654
• Pull request review comment event: 146
• Pull request review event: 147

Last Year

• Create event: 91
• Commit comment event: 1
• Release event: 7
• Delete event: 73
• Pull request event: 71
• Watch event: 3
• Issue comment event: 78
• Push event: 413
• Pull request review event: 98
• Pull request review comment event: 100

---

Committers metadata

Last synced: 4 days ago

Name	Email	Commits
Oliver-BE	o****s@g****m	563
Matt Spencer	s****r@g****m	548
RJ Sheperd	r****d@g****m	209
Joel Iniguez	j****z@g****m	106
drew verlee	d****e@g****m	72
Gary Johnson	l****c@g****m	65
Daniel Keenan	h****e@g****m	60
Daniel Habib Vieira da Silva	d****0@g****m	26
Sif	s****i@s****m	21
Daniel Silva	d****a@s****m	6
Arthur G Luz	a****z@s****m	5
Andrew Carlile	4****t	2
Josh Clark	j****4@g****m	2
Gary Johnson	l****c@d****g	2
David S Saah	d****h@s****m	1

Committer domains:

• sig-gis.com: 4
• disroot.org: 1

---

Issue and Pull Request metadata

Last synced: 4 days ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pyregence/pyregence

---

---

Score: 5.105945473900581