Points3D, LineStrips3D, Transform3D
Static screenshots and videos belong in the past. In this guide, we will walk through deploying a live, interactive webpage integrated with Rerun. By embedding a hosted Rerun viewer, you are not just showing your results — you are handing your audience the keys to explore your data in 3D, scrub through timelines, and inspect your model's logic in real-time.
In a fast-moving industry, the ability to provide an immersive, 'hands-on' demo is the difference between a project that gets glanced at and one that gets remembered. Here we will go through the steps to create your webpage with Rerun integrated, you will see that it is simple and quick process that does not take away valuable development or writing time.
You can see the resulting webpage here.
Below you will find a collection of useful Rerun resources for this example:
- Embed Rerun in Web pages
- API pages:
- Rerun web-viewer examples:
This guide goes from nothing to a complete live webpage hosted via GitHub Pages. We assume you are running all commands within the webpage_example repository folder and using the Pixi package manager for environment setup (only needed if you want to generate the recordings dataset yourself). To build and host the webpage locally we make use of npm.
The first thing you need is data. Record your streams (point clouds, images, transforms) and save them as an .rrd file. For this example, we will use the getting started guide to produce our data. We have prepared the code in the file webpage_example/create_dataset.py. To save the data to a file, instead of logging it to the Rerun viewer, we call the rerun.save before logging any of the data. You can also use Save recording... from the file menu to save the .rrd file from the Rerun viewer.
Second we want to setup the blueprint, to configure what the user will be seeing in the Rerun viewer when opening the page. If you want, you can add the blueprint directly to the .rrd file we created in the first step. The benefit of separating them is that you can update the blueprint separately without having to regenerate the .rrd file. In this example, the generating of the .rrd is quick and the file is small, but perhaps your data is larger which means it will take longer for you to produce and upload the .rrd file, compared to updating and uploading the blueprint (.rbl) file, which is typically much smaller.
The .rbl file is created by commenting out rerun.save from the webpage_example/create_dataset.py file and instead run rr.spawn(). This will open the viewer and log the data to the viewer. Then we setup the view to our liking and use Save blueprint... from the file menu.
For web deployment, keeping file sizes optimized is key for fast loading. Prune your data and keep only what is neccessary to enable a seemless experience.
The webpage needs to "fetch" the data from somewhere. You can host the data wherever you please. If the data is small enough, you can store it directly in the repository itself. Otherwise, you may use a service, such as Google Drive, OneDrive, or similar to store your data.
In this example, we are hosting the dna_structure.rrb and dna_structure.rbl in the recordings folder of this repository.
Github have great documentation for GitHub Pages, which we recommend you reading. Here we will go through the approach that we took.
Create a Github repository, it is good to at least have a README.md file in the repository.
Next, we want to enable Github pages. This is done by going to your repository in your browser, go to Settings and then select Pages. Under Build and deployment select GitHub Actions as the Source.
Now we should setup the workflow that deploys are Github pages webpage. Create a file deploy.yml inside the github/workflows folder of your Github repository. You may have to create the folders yourself. The contents of the file should be:
# Simple workflow for deploying static content to GitHub Pages
name: Deploy app to GitHub Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
defaults:
run:
working-directory: docs
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm install
- name: Build
run: npm run build
env:
REPOSITORY: ${{ github.event.repository.name }}
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload dist repository
path: "./docs/dist"
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
This workflow assumes that the webpage is located in a folder docs in the root of our repository, on the main branch. You may want to update this as you see fit. It will deploy the website for every push to main.
Everything related to the webpage in this repository (except for the workflow) has been put into the docs folder. To start working on your webpage, you can copy this repository's docs folder to your repository. After you have pushed the code, you need to wait for the Github action to finish deploying your webpage. You can see when it has finished by visiting the repository in your web browser.
Update the files inside the docs folder to reflect on your work. There are mainly four files that you probably want to edit:
docs/index.html- Here you fill in the content of your webpage.
docs/style.css- Here you configure the style of your webpage. The supplied style supports both light and dark theme, and will switch between them based on the browsers/systems settings.
docs/src/main.ts- Here is where we create the interactive Rerun viewer on the webpage. You most likely would want to change the variables
rrdandrblto point to your own files.
- Here is where we create the interactive Rerun viewer on the webpage. You most likely would want to change the variables
docs/package.json- Make sure to sync the Rerun version you use to generate the
.rrband.rblfiles with the version of the version of@rerun-io/web-viewerspecified in this file.
- Make sure to sync the Rerun version you use to generate the
You probably also want to upload your own assets (images, videos, icons), to the docs/assets folder and use them inside docs/index.html.
Unless you want to do something more advanced, you can probably leave the other files inside the docs folder as they are. Changes to those files are out-of-scope for this example.
After you have pushed your code, you need to wait for the Github action to finish deploying your webpage. You can see when it has finished by visiting the repository in your web browser.
You will be able to access your site at: https://your-username.github.io/your-repo-name, replace your-username with your Github username and your-repo-name with the name of the repository you created.
You can test your page locally by cloning the repo and running:
cd docs
npm install
npm run devand then open the link that is printed.
In this repository we have also made a Pixi task so you can run:
pixi run host_webpageand it will run those commands for you.
- Make sure to keep the data files (
.rrdand.rbl) at the same version as the@rerun-io/web-viewerversion specified indocs/package.json. In this example repo, that means that thererun-sdkversion specified inpyproject.toml, when generating the data, is the same as the@rerun-io/web-viewerversion specified indocs/package.json, when viewing the data.