Installing Shaper

Shaper is a single binary which can be downloaded directly, but it’s easiest to use the pre-built Docker image, Python package or NPM package.

We recommend you to use the Docker image to run Shaper in production to ensure a consistent environment.

For developing dashboards locally using the file-based workflow we recommend using the NPM or Python package.

Docker

Run the image directly with the Docker CLI:

1. Make sure you have Docker installed and running.
2. Start the container:

   docker run --rm -it -p5454:5454 taleshape/shaper

3. Open http://localhost:5454 in your browser

Persisting Data

To persist data and changes you made, you need to mount a volume to the container. Shaper stores data in the /data directory inside the container. Mount a local directory to this path using the -v option in Docker:

docker run --rm -it -p5454:5454 -v ./mydata:/data taleshape/shaper

Python

Install the shaper-bin PyPI when using Shaper locally if you already have Python installed (you likely do).

Python’s package manager pip manages the version for you and handles downloading the correct binary for your system.

If you have pipx installed, you can run Shaper via pipx without explicitly installing it:

pipx run shaper-bin

Install Shaper globally to make the shaper binary available in your PATH:

pipx install shaper-bin

You can also use pip to install Shaper as a dependency in your project. This is useful to ensure everyone working on the project uses the same version of shaper:

pip install shaper-bin

NPM

Install the @taleshape/shaper NPM package when using Shaper locally if your project already uses Node.js. Then you can manage dependencies all in one place.

NPM manages the version for you and handles downloading the correct binary for your system.

Run Shaper via npx without explicitly installing it:

npx @taleshape/shaper

Install Shaper globally to make the shaper binary available in your PATH:

sudo npm install -g @taleshape/shaper

Rerun the install command to update to the latest version.

You can also install Shaper as a dependency in your project. This is useful to ensure everyone working on the project uses the same version of shaper:

npm install @taleshape/shaper

Data Storage

By default Shaper stores data in the home directory at ~/.shaper.

Specify a different location using the --data-dir (short -d) option:

npx @taleshape/shaper -d .shaperdata

This will create a .shaperdata directory in the current working directory and store all data there.

Configuration

For more configuration options see:

Configuration Options

Chrome Dependency

To download PDFs Shaper uses a headless Chrome browser.

The Docker image already includes a lightweight version of Chrome.

When using the NPM package or binaries directly, you need to make sure you have a recent version of Google Chrome or Chromium installed on your system.

Binaries

Download Shaper binaries directly from the Github Releases page.

You need to download the correct binary for your system.

Make sure the binary is executable:

chmod +x shaper

When using the binaries directly you have to manage the version yourself.

We also recommend you use the provided SHA256 checksums to verify the integrity of the downloaded binary to prevent supply chain attacks.

Supported Platforms

Currently only Linux and MacOS with AMD64 or ARM64 architectures are supported, but the Docker image should run on Windows as well.

See Github for progress on Windows support.