Skip to content

Add local dev carto API workflow and docs #172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wagnerlmichael wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add local dev carto API workflow and docs #172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d0ca38
Add local dev carto API workflow
wagnerlmichael Oct 9, 2026
7571e0a
Update README.md
wagnerlmichael Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 38 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,37 @@ hugo serve
3. Any reports that [you have generated](#generating-reports)
will be available in a browser at http://localhost:1313/.

### Setting up a Carto API key for local maps

Report maps use [Carto](https://carto.com/) basemap tiles. The API key that
we use for deployed reports only works on the prod and staging hosts, so maps
on the development server will show a Carto watermark unless you set up your
own key for local development. You can skip this step if you don't need
maps locally.

1. [Sign up for a Carto API key](https://carto.com/basemaps/apikey/) using
your work email.
2. Under **Restrictions**, enable **Restrict to specific websites
(Referer)** and enter `localhost` and `127.0.0.1`. Leave the other
restrictions off. See the [Carto
docs](https://docs.carto.com/faqs/carto-basemaps#why-are-my-tiles-refused-403-when-my-key-has-website-restrictions)
for details on local development keys.
3. Add the key to your shell profile (e.g. `~/.bashrc`), then restart your
shell:

```
export HUGO_CARTO_KEY=<your_key>
```
Comment on lines +49 to +54

@jeancochrane jeancochrane Oct 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Thought, non-blocking] I think this is a fine approach, but I keep my dotfiles under version control in a public repo, so I didn't want to stash this API key in my bashrc. Another alternative is just to store it in a password manager and then set the env var like so whenever you need to generate reports:

HUGO_CARTO_KEY=<my_key> python3 scripts/generate_homeval/generate_homeval.py ...

I don't necessarily think we need to document this flow, just flagging it in case it's interesting!

@wagnerlmichael wagnerlmichael Oct 9, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe the env method should be left for the user to approach on their own? Or do you think we should have some sort of instruction for it here? I'm not sure

@jeancochrane jeancochrane Oct 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think your instructions are fine!


4. Run `hugo serve` and open a report that has a map. The tiles should load

@jeancochrane jeancochrane Oct 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Thought, non-blocking] I think users will probably need to generate a report before they can run hugo serve and see maps, right? Not sure if that should be documented here, but I temporarily forgot about that step while testing.

with no watermark, and in your browser's DevTools, the Network tab should
show requests to `basemaps.cartocdn.com` containing `?key=<your_key>`.

> [!WARNING]
> Don't commit your local key. This repo is public, and the referer
> restriction doesn't stop anyone else from using a key on their own
> `localhost`.

### Generating reports

You can use the [`generate_homeval`
Expand All @@ -53,9 +84,15 @@ comps run ID:
```
python3 scripts/generate_homeval/generate_homeval.py \
--run-id <your_comps_run_id> \
--pin <one_or_more_space_separated_pins>
--pin <one_or_more_space_separated_pins> \
--skip-html
```

The `--skip-html` flag keeps the generated Markdown files in `hugo/content/`
so that the [development server](#running-a-development-server) can render
them. Without it, the script builds static HTML into `hugo/public/` and then
deletes the Markdown, so the reports won't be available from `hugo serve`.

@wagnerlmichael wagnerlmichael Oct 9, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added an explanation here about how when testing locally the hugo serve just needs the markdown, not the html flow through actions

If you're not sure which comps run ID to use, but you want to use the final
comps run for a given year, see the `pinval.model_run` table.

Expand Down
6 changes: 4 additions & 2 deletions hugo/layouts/report.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -834,8 +834,10 @@ <h3 class="mb-3">Model Estimate for Card {{ .card.card_num }}</h3>
14
);

{{/* Carto basemap API key, restricted to the prod and staging hosts */}}
const cartoKey = {{ cond hugo.IsServer "" "cb1_45dr_1_d676f2f54005676a45bee03c" }};
{{/* Carto basemap API key. Deployed builds use a key restricted to the
prod and staging hosts; `hugo serve` reads a local key from the
HUGO_CARTO_KEY env var (see README) */}}
const cartoKey = {{ cond hugo.IsServer (getenv "HUGO_CARTO_KEY") "cb1_45dr_1_d676f2f54005676a45bee03c" }};

@wagnerlmichael wagnerlmichael Oct 9, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://gohugo.io/functions/hugo/isserver/


// Add tile layer
L.tileLayer(
Expand Down
Loading