Skip to content

Commit 8841d01

Browse files
mbostocktophtucker
mbostock
and
tophtucker
authored
docs for cloud deprecation (#1971)
* docs for cloud deprecation * dist, not src/.observablehq/dist * Update docs/deploying.md Co-authored-by: Toph Tucker <[email protected]> * contents: read permission --------- Co-authored-by: Toph Tucker <[email protected]>
1 parent 82412a4 commit 8841d01

File tree

3 files changed

+33
-158
lines changed

3 files changed

+33
-158
lines changed

‎docs/deploying.md

Lines changed: 24 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,14 @@
11
# Deploying
22

3-
You can host your built Framework app on any static site hosting service, or self-host it with any static site server. This guide covers deploying to [Observable Cloud](https://observablehq.com/platform/cloud), which is the easiest way to host your Framework app as support is built-in. We’ll also cover setting up automated deploys with GitHub Actions.
3+
You can host your built Framework app on any static site hosting service, or self-host it with any static site server. This guide covers automating deploys to [GitHub Pages](https://pages.github.com/) with [GitHub Actions](https://github.com/features/actions), and assumes that you are hosting your Framework project’s git repository on GitHub.
44

55
<div class="tip">
66

77
If you don’t yet have an app ready to deploy, create one by following our [Getting started guide](./getting-started).
88

99
</div>
1010

11-
## Manual deploys
12-
13-
To deploy your app, run the deploy command:
14-
15-
```sh
16-
npm run deploy
17-
```
18-
19-
<div class="tip">
20-
21-
Deploying automatically creates a [deploy configuration file](#deploy-configuration) (`.observablehq/deploy.json`) if it does not already exist. You should commit this file to git; it is required for automated deploys, and lets you re-deploy manually with fewer prompts.
22-
23-
</div>
24-
25-
The first time you deploy an app, you will be prompted to configure the app’s _slug_ (which determines its URL), access level, and other details. If you aren’t yet signed-in to Observable, you will also be prompted to sign-in.
26-
27-
When the deploy command finishes, it prints a link to observablehq.cloud where you can view your deployed app. If you choose _private_ as the access level, that link will only be accessible to members of your Observable workspace. (You can invite people to your workspace by going to observablehq.com.) If you choose _public_, you can share your app link with anyone. You can change the access level of an app later [from your Data apps page](https://observablehq.com/select-workspace?next=projects).
28-
29-
<div class="tip">
30-
31-
To see more available options when deploying:
32-
33-
```sh run=false
34-
npm run deploy -- --help
35-
```
36-
37-
</div>
38-
39-
## Automated deploys
40-
41-
After deploying an app manually at least once, Observable can handle subsequent deploys for you automatically. You can automate deploys both [on commit](https://observablehq.com/documentation/data-apps/github) (whenever you push a new commit to your project’s default branch) and [on schedule](https://observablehq.com/documentation/data-apps/schedules) (such as daily or weekly).
42-
43-
Automatic deploys — also called _continuous deployment_ or _CD_ — ensure that your data is always up to date, and that any changes you make to your app are immediately reflected in the deployed version.
44-
45-
On your app settings page on Observable, open the **Build settings** tab to set up a link to a GitHub repository hosting your project’s files. Observable will then listen for changes in the repo and deploy the app automatically.
46-
47-
The settings page also allows you to trigger a manual deploy on Observable Cloud, add secrets (for data loaders to use private APIs and passwords), view logs, configure sharing, _etc._ For details, see the [Building & deploying](https://observablehq.com/documentation/data-apps/deploys) documentation.
48-
49-
## GitHub Actions
50-
51-
As an alternative to building on Observable Cloud, you can use [GitHub Actions](https://github.com/features/actions) and have GitHub build a new version of your app and deploy it to Observable. In your git repository, create and commit a file at `.github/workflows/deploy.yml`. Here is a starting example:
11+
In your git repository, create the file `.github/workflows/deploy.yml` with the following contents:
5212

5313
```yaml
5414
name: Deploy
@@ -64,59 +24,37 @@ on:
6424
jobs:
6525
deploy:
6626
runs-on: ubuntu-latest
27+
permissions:
28+
contents: read
29+
pages: write
30+
id-token: write
31+
environment:
32+
name: github-pages
33+
url: ${{ steps.deployment.outputs.page_url }}
6734
steps:
6835
- uses: actions/checkout@v4
6936
- uses: actions/setup-node@v4
7037
with:
71-
node-version: 20
38+
node-version: 22
7239
cache: npm
7340
- run: npm ci
7441
- run: npm run build
75-
- name: Deploy to Observable Cloud
76-
# This parameter to `--message` will use the latest commit message
77-
run: npm run deploy -- --message "$(git log -1 --pretty=%s)"
78-
env:
79-
# Authentication information. See below for how to set this up.
80-
OBSERVABLE_TOKEN: ${{ secrets.OBSERVABLE_TOKEN }}
42+
- uses: actions/configure-pages@v4
43+
- uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: dist
46+
- name: Deploy
47+
id: deployment
48+
uses: actions/deploy-pages@v4
8149
```
8250
83-
<div class="tip">As shown above, deploy messages can be set using <code>--message</code>. This is especially useful for continuous deployment from a git repository: the message can include the SHA, author, and message of the latest commit.</div>
84-
85-
When deploying automatically, you can’t sign-in in your browser the way you did for manual deploys; instead, your GitHub action will authenticate using an Observable API key (also known as a _token_ and referred to as `OBSERVABLE_TOKEN` above).
86-
87-
To create an API key:
88-
89-
1. Open the [API Key settings](https://observablehq.com/select-workspace?next=api-keys-settings) for your Observable workspace.
90-
2. Click **New API Key**.
91-
3. Check the **Deploy new versions of projects** checkbox. <!-- TODO apps -->
92-
4. Give your key a description, such as “Deploy via GitHub Actions”.
93-
5. Click **Create API Key**.
94-
95-
<div class="caution">
96-
97-
The token you create is the equivalent of a password giving write access to your hosted app. **Do not commit it to git** or share it with anyone you don’t trust. If you accidentally expose your key, you can go back to your settings to immediately revoke it (and create a new key).
98-
99-
</div>
100-
101-
In a moment, you’ll copy-paste your new Observable API key, so leave this window open for now. (If you accidentally close the window, you can delete the old key and create a new one. For security, API keys are only shown once upon creation.)
102-
103-
To authenticate with Observable and to access the Observable API key securely from our Github action, we’ll use a [GitHub secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
104-
105-
To create a GitHub secret, in a new window:
51+
Commit this file to your main branch and push to GitHub. Then follow [GitHub’s instructions](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) to specify GitHub Actions as the source for GitHub Pages.
10652
107-
1. Go to your GitHub repository.
108-
2. In the top navigation, click **Settings**.
109-
3. In the left sidebar, click **Secrets and variables**, then **Actions**.
110-
4. Click **New repository secret**.
111-
5. In the **Name** field, enter `OBSERVABLE_TOKEN`.
112-
6. In the **Secret** field, paste the API key you created on Observable.
113-
7. Click **Add secret**.
114-
115-
After you’ve performed these steps, the `deploy.yml` above will automatically build and deploy your app 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).
53+
After you’ve performed these steps, the `deploy.yml` above will automatically build and deploy your app once per day (to keep your data up-to-date), as well as whenever you push new commits to your GitHub repository’s main branch (so you can make changes at any time). You will also be able to manually trigger a deploy through GitHub’s user interface. If you like, you can disable any of these triggers (`push`, `schedule`, or `workflow_dispatch`) by updating the `deploy.yml` file.
11654

11755
### Caching
11856

119-
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`:
57+
If some of your data loaders take a long time to run, or simply don’t need to be updated every time you build, 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 `npm run build`:
12058

12159
```yaml
12260
jobs:
@@ -133,28 +71,10 @@ jobs:
13371
# …
13472
```
13573

136-
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.
137-
138-
<div class="note">You’ll need to edit the paths above if you’ve configured a source root other than <code>src</code>.</div>
74+
<div class="note">
13975

140-
## Deploy configuration
76+
This will only cache data loaders that live under <code>src/data</code>. You’ll need to edit the paths above if you’ve configured a source root other than <code>src</code>, or if the data loaders you want to cache live elsewhere.
14177

142-
The deploy command creates a file at <code>.observablehq/deploy.json</code> under the source root (typically <code>src</code>) with information on where to deploy the app. This file allows you to re-deploy an app without having to repeat where you want the app to live on Observable.
143-
144-
The contents of the deploy config file look like this:
145-
146-
```json run=false
147-
{
148-
"projectId": "0123456789abcdef",
149-
"projectSlug": "hello-framework",
150-
"workspaceLogin": "acme"
151-
}
152-
```
153-
154-
To store the deploy config file somewhere else, use the `--deploy-config` argument. For example, to create a “staging” deploy to share early versions of your app, you could use a `deploy-staging.json` like so:
155-
156-
```sh
157-
npm run deploy -- --deploy-config=src/.observablehq/deploy-staging.json
158-
```
78+
</div>
15979

160-
If the specified config file does not yet exist, you will again be prompted to choose or create a new app; the resulting configuration will then be saved to the specified file. You can re-deploy to staging by passing the same `--deploy-config` argument; or you can deploy to “production” by not specifying the `--deploy-config` argument to use the default deploy config.
80+
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.

‎docs/embeds.md

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ In addition to standalone apps, you can use Framework to embed interactive views
1010
- [exported files](#exported-files) for hotlinking images, data, and other assets, or
1111
- [iframe embeds](#iframe-embeds) for compatibility.
1212

13-
You can deploy to Observable Cloud for [additional features](https://observablehq.com/documentation/data-apps/embeds)<a href="https://github.com/observablehq/framework/releases/tag/v1.13.0" class="observablehq-version-badge" data-version="^1.13.0" title="Added in v1.13.0"></a> including secure private embedding on approved domains and analytics to see which exports are used.
14-
1513
## Exported modules
1614

1715
Framework allows [JavaScript modules](./imports#local-imports) to be exported for use in another application. Exported modules are vanilla JavaScript and behave identically in an external web application as on a Framework page. As with local modules, exported modules can load data from a [static file](./files) or a [data loader](./data-loaders), [import](./imports) other local modules, and import libraries from [npm](./imports#npm-imports) or [JSR](./imports#jsr-imports).
@@ -70,7 +68,7 @@ An exported module can then be imported into a vanilla web application like so:
7068
```html run=false
7169
<script type="module">
7270
73-
import {Chart} from "https://my-workspace.observablehq.cloud/my-app/chart.js";
71+
import {Chart} from "https://my-app.example.com/chart.js";
7472
7573
document.body.append(await Chart());
7674
@@ -79,7 +77,7 @@ document.body.append(await Chart());
7977

8078
<div class="tip">
8179

82-
Observable Cloud supports [cross-origin resource sharing](https://observablehq.com/documentation/data-apps/embeds#cors) (CORS), which is needed for exported modules.
80+
You must [enable cross-origin resource sharing](https://enable-cors.org/) (CORS) on your hosting provider to import exported modules across domains.
8381

8482
</div>
8583

@@ -93,7 +91,7 @@ export function EmbedChart() {
9391

9492
useEffect(() => {
9593
let parent = ref.current, child;
96-
import("https://my-workspace.observablehq.cloud/my-app/chart.js")
94+
import("https://my-app.example.com/chart.js")
9795
.then(({Chart}) => Chart())
9896
.then((chart) => parent?.append((child = chart)));
9997
return () => ((parent = null), child?.remove());
@@ -158,7 +156,7 @@ pager: false
158156
For the page `/chart`, you can declare an iframe like so:
159157
160158
```html run=false
161-
<iframe scrolling="no" src="https://my-workspace.observablehq.cloud/my-app/chart"></iframe>
159+
<iframe scrolling="no" src="https://my-app.example.com/chart"></iframe>
162160
```
163161
164162
With a little bit of additional JavaScript, you can also implement [responsive iframe embeds](https://observablehq.observablehq.cloud/framework-example-responsive-iframe/) which resize automatically to fit the content of the page.

‎docs/getting-started.md

Lines changed: 5 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ const digraph = dot`digraph {
7474
${digraph}
7575
</figure>
7676

77-
First you’ll setup your local development environment by [**creating**](#1-create) a new project. A project contains all the source code needed to build an app. Next you’ll [**develop**](#2-develop): an iterative process where you save changes to source files in your editor while previewing the result in your browser. When you’re ready to share, it’s time to [**publish**](#3-publish): you can either build a static site for self-hosting or deploy directly to Observable. Lastly, you can invite people to view your app!
77+
First you’ll setup your local development environment by [**creating**](#1-create) a new project. A project contains all the source code needed to build an app. Next you’ll [**develop**](#2-develop): an iterative process where you save changes to source files in your editor while previewing the result in your browser. When you’re ready to share, it’s time to [**publish**](#3-publish): you build and deploy your static site to your preferred hosting provider.
7878

7979
These are just first steps. You can continue to develop apps after publishing, and republish as needed. You can also setup continuous deployment to publish your app automatically on commit or on schedule. We’ll cover these [next steps](#next-steps) briefly below.
8080

@@ -476,52 +476,7 @@ _Ta-da!_ 🎉 Perhaps not the most exciting dashboard yet, but it has potential!
476476

477477
## 3. Publish
478478

479-
When you’re ready to share your app — either privately or publicly — you can quickly deploy it to [Observable](https://observablehq.com) using the `deploy` command:
480-
481-
<pre data-copy>npm run deploy</pre>
482-
483-
Or with Yarn:
484-
485-
<pre data-copy>yarn deploy</pre>
486-
487-
<div class="note">If you don’t have an Observable account yet, you will be prompted to sign up. Observable is free for individuals and small teams, and we offer paid tiers for larger teams.</div>
488-
489-
This command will ask you a few questions to configure your deploy, including which Observable workspace to use and whether the app should be public or private. You can also enter an optional message to associate with the deploy, but for now feel free to leave this blank by hitting Enter.
490-
491-
When deploy completes, Framework will show your app’s URL on observablehq.cloud, like below. From there you can invite people to your private workspace to see your app, or make your app public so anyone can see it.
492-
493-
<pre data-copy="none">
494-
<span class="muted">┌</span> <span class="invert"> observable deploy </span>
495-
<span class="muted">│</span>
496-
<span class="blue">●</span> To configure deploy, we need to ask you a few questions.
497-
<span class="muted">│</span>
498-
<span class="green">◇</span> Which Observable workspace do you want to use?
499-
<span class="muted">│ Example Inc. (@example)</span>
500-
<span class="muted">│</span>
501-
<span class="green">◇</span> Which app do you want to use?
502-
<span class="muted">│ Create a new app</span>
503-
<span class="muted">│</span>
504-
<span class="green">◇</span> What slug do you want to use?
505-
<span class="muted">│ hello-framework</span>
506-
<span class="muted">│</span>
507-
<span class="green">◇</span> Who is allowed to access your app?
508-
<span class="muted">│ Private</span>
509-
<span class="muted">│</span>
510-
<span class="green">◇</span> What changed in this deploy?
511-
<span class="muted">│</span> <span class="muted">Enter a deploy message (optional)</span>
512-
<span class="muted">│</span>
513-
<span class="green">◇</span> 18 uploaded
514-
<span class="muted">│</span>
515-
<span class="green">◇</span> Deploy complete
516-
<span class="muted">│</span>
517-
<span class="muted">└</span> <span class="muted">Deployed app now visible at <u>https://example.observablehq.cloud/hello-framework/</u></span>
518-
</pre>
519-
520-
<div class="tip">Your deploy configuration is saved to <code>src<span class="wbr">/</span>.observablehq<span class="wbr">/</span>deploy.json</code>. When collaborating on an app, you should commit this file to git so your collaborators don’t have to separately configure deploy.</div>
521-
522-
### Self hosting
523-
524-
Of course, you don’t have to deploy to Observable — Framework apps are simply static sites, so you can host them anywhere!
479+
When you’re ready to share your app, you can quickly build and deploy it to your preferred hosting provider, such as GitHub Pages.
525480

526481
To build your app with npm, run:
527482

@@ -531,7 +486,7 @@ Or with Yarn:
531486

532487
<pre data-copy>yarn build</pre>
533488

534-
The <code>build</code> command generates the `dist` directory; you can then copy this directory to your static site server or preferred hosting service. To preview your built app locally, you can use a local static HTTP server such as [http-server](https://github.com/http-party/http-server):
489+
The <code>build</code> command generates the `dist` directory; you can then upload this directory to your preferred hosting provider or copy it to your static site server for self-hosting. To preview your built app locally, you can use a local static HTTP server such as [http-server](https://github.com/http-party/http-server):
535490

536491
<pre data-copy>npx http-server dist</pre>
537492

@@ -541,6 +496,8 @@ The <code>build</code> command generates the `dist` directory; you can then copy
541496
<a href="https://github.com/actions/deploy-pages">deploy-pages</a>, and
542497
<a href="https://github.com/actions/upload-pages-artifact">upload-pages-artifact</a>), you may need to create a <code>.nojekyll</code> file in your <code>dist</code> folder after building. See GitHub’s documentation on <a href="https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#static-site-generators">static site generators</a> for more.</div>
543498

499+
To deploy your app to GitHub Pages using GitHub Actions, read our [Deploying guide](./deploying).
500+
544501
## Next steps
545502

546503
Here are a few more tips.

0 commit comments

Comments
 (0)