|
| 1 | +# Deploying |
| 2 | + |
| 3 | +When time comes to share your project, you have many options for deploying it for others to see. Framework is compatible with many static site hosts and automation environments. In this guide we’ll focus on deploying to Observable manually, then with GitHub Actions. |
| 4 | + |
| 5 | +## Manually deploying to Observable |
| 6 | + |
| 7 | +If you don’t already have a project to deploy, you can create one by following [getting-started](./getting-started). First, make sure that your project builds without error: |
| 8 | + |
| 9 | +```sh |
| 10 | +$ npm run build |
| 11 | +``` |
| 12 | + |
| 13 | +Once that is done you can deploy to Observable with the command |
| 14 | + |
| 15 | +```sh |
| 16 | +$ npm run deploy |
| 17 | +``` |
| 18 | + |
| 19 | +The first time you run this command, you will be prompted for details needed to set up the project on the server, such as the project's _slug_ (which determines its URL), and the access level. If you don’t already have an Observable account or aren’t signed in, this command will also guide you through setting that up. |
| 20 | + |
| 21 | +When the deploy command finishes, it prints a link to observablehq.cloud where you can view your deployed project. If you choose “private” as the access level, you can now share that link with anyone who is a member of your workspace. If you chose “public”, you can share that link with anyone and they’ll be able to see your Framework project. |
| 22 | + |
| 23 | +<div class="note">The deploy command creates a file at <code>docs/.observablehq/deploy.json</code> with information on where to deploy the project. It is required for automated deploys. You should commit it to git to make it available to GitHub Actions. (If you have configured a source root besides <code>docs/</code>, the file will be placed there instead.)</div> |
| 24 | + |
| 25 | +## Automated deploys to Observable |
| 26 | + |
| 27 | +To set up automatic deploys, we’ll be using [GitHub actions](https://github.com/features/actions). In your git repository, create and commit a file at `.github/workflows/deploy.yml`. Here is a starting example: |
| 28 | + |
| 29 | +```yaml |
| 30 | +name: Deploy |
| 31 | +on: |
| 32 | + # Run this workflow whenever a new commit is pushed to main. |
| 33 | + push: {branches: [main]} |
| 34 | + # Run this workflow once per day, at 10:15 UTC |
| 35 | + schedule: [{cron: "15 10 * * *"}] |
| 36 | + # Run this workflow when triggered manually in GitHub's UI. |
| 37 | + workflow_dispatch: {} |
| 38 | +jobs: |
| 39 | + deploy: |
| 40 | + runs-on: ubuntu-latest |
| 41 | + steps: |
| 42 | + - uses: actions/checkout@v4 |
| 43 | + - uses: actions/setup-node@v4 |
| 44 | + with: |
| 45 | + node-version: 20 |
| 46 | + cache: npm |
| 47 | + - run: npm ci |
| 48 | + - run: npm run build |
| 49 | + - name: Deploy to Observable Cloud |
| 50 | + # This parameter to `--message` will use the latest commit message |
| 51 | + run: npm run deploy -- --message "$(git log -1 --pretty=%s)" |
| 52 | + env: |
| 53 | + # Authentication information. See below for how to set this up. |
| 54 | + OBSERVABLE_TOKEN: ${{ secrets.OBSERVABLE_TOKEN }} |
| 55 | +``` |
| 56 | +
|
| 57 | +When deploying automatically, you won’t be able to login with a browser the way you did for manual deploys. Instead, you will authenticate via the environment variable `OBSERVABLE_TOKEN`, using an API key from Observable. |
| 58 | + |
| 59 | +To create a token, go to https://observablehq.com and open your workspace settings. Choose “API keys”. From there, create a new key, and assign it the "Deploy new versions of projects" scope. |
| 60 | + |
| 61 | +That token is the equivalent of a password giving write access to your hosted project. **Do not commit it to git** (and, if it is exposed in any way, take a minute to revoke it and create a new one instead—or contact support). |
| 62 | + |
| 63 | +To pass this information securely to the Github action (so it can effectively be authorized to deploy the project to Observable), we’ll use GitHub secrets. Sign in to the settings of your GitHub account, and add a secret named `OBSERVABLE_TOKEN`. See [GitHub’s documentation](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) for more information about secrets. |
| 64 | + |
| 65 | +This `deploy.yml` will automatically build and deploy your project once per day (to keep your data up-to-date), as well as whenever you push a new version of the code to your repository (so you can make changes at any time). |
| 66 | + |
| 67 | +### Caching |
| 68 | + |
| 69 | +If some of your data loaders take a long time to run, or simply don’t need to be updated every time you modify the code, you can set up caching to automatically re-use existing data from previous builds. To do that, add the following steps to your `deploy.yml` before you run `build`: |
| 70 | + |
| 71 | +```yaml |
| 72 | +jobs: |
| 73 | + deploy: |
| 74 | + steps: |
| 75 | + # ... |
| 76 | + - id: date |
| 77 | + run: echo "date=$(TZ=America/Los_Angeles date +'%Y-%m-%d')" >> $GITHUB_OUTPUT |
| 78 | + - id: cache-data |
| 79 | + uses: actions/cache@v4 |
| 80 | + with: |
| 81 | + path: docs/.observablehq/cache |
| 82 | + key: data-${{ hashFiles('docs/data/*') }}-${{ steps.date.outputs.date }} |
| 83 | + - if: steps.cache-data.outputs.cache-hit == 'true' |
| 84 | + run: find docs/.observablehq/cache -type f -exec touch {} + |
| 85 | + # ... |
| 86 | +``` |
| 87 | + |
| 88 | +This uses one cache per calendar day (in the “America/Los_Angeles” time zone). If you deploy multiple times in a day, the results of your data loaders will be reused on the second and subsequent runs. You can customize the `date` and `cache-data` steps to change the cadence of the caching. For example you could use `date +'%Y-%U'` to cache data for a week or `date +'%Y-%m-%dT%H` to cache it for only an hour. |
| 89 | + |
| 90 | +<div class="note">You’ll need to change the paths used in this config if <code>observablehq.config.js</code> points to a different <code>root</code>.</div> |
| 91 | + |
| 92 | +## Deploying to other services |
| 93 | + |
| 94 | +The output of Observable Framework is set of static files that can be hosted by many services. To build a hostable copy of your project, run: |
| 95 | + |
| 96 | +```sh |
| 97 | +$ npm run build |
| 98 | +``` |
| 99 | + |
| 100 | +Then you can upload the contents of your `dist/` directory to your static webhost of choice. Some webhosts may need the `cleanUrls` option <a href="https://github.com/observablehq/framework/releases/tag/v1.3.0" target="_blank" class="observablehq-version-badge" data-version="^1.3.0" title="Added in v1.3.0"></a> set to false in your project configuration file. For details and other options, see [configuration](./config). |
0 commit comments