Docs: Deploying Leptos apps

[gbj]

I've arrived at the final chapter in the Leptos book: Deployment. This is one I'd like to crowd-source a little, because a) I'm weak on this stuff and b) a lot of you have deployed apps in interesting ways, I'm sure.

If you have any info to share on deployment, please post it in this thread and I'll put it together into a chapter!

Many thanks.

[BrookJeynes]

Hey Greg,

Here's how I got Vercel to deploy a Leptos CSR project through GitHub actions (with linting, clippy, and build checking + testing). This method also allows for preview deploys on pull requests.

Special thanks to @Skyliegirl33 for helping me set this up

Vercel setup

1. Create a new project
2. Ensure
   • Build command is left empty with Override on
   • Output directory is changed to dist (or wherever you have the build output)
     

Setup Vercel credentials for GitHub Actions

Both of these actions will need your Vercel credentials setup in GitHub secrets

1. Retrieve your Vercel Access Token
2. Install the Vercel CLI and run vercel login
3. Inside your folder, run vercel link to create a new Vercel project
4. Inside the generated .vercel folder, save the projectId and orgId from the project.json
5. Inside GitHub, add VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID as secrets

Instructions from https://vercel.com/guides/how-can-i-use-github-actions-with-vercel

GitHub Actions

1. Pull request - Action to format, Clippy, build, and test. This will first format and clippy, then build, then test. It will then create a preview deployment for the PR and comment with the preview link. This will also create a preview environment for your repo.

name: Rust

on:
  pull_request:
    branches: [ "main" ]
    
  workflow_dispatch:

env:
  CARGO_TERM_COLOR: always
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  fmt:
    name: Rustfmt
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@nightly
        with:
          components: rustfmt
      - name: Enforce formatting
        run: cargo fmt --check

  clippy:
    name: Clippy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@nightly
        with:
          components: clippy
      - uses: Swatinem/rust-cache@v2
      - name: Linting
        run: cargo clippy -- -D warnings

  test:
    name: Test
    runs-on: ubuntu-latest
    needs: [fmt, clippy]
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@nightly
      - uses: Swatinem/rust-cache@v2
      - name: Run tests
        run: cargo test

  build-and-preview-deploy:
    runs-on: ubuntu-latest
    name: Build and Preview Deploy
    needs: [test]
    permissions:
      pull-requests: write
    environment:
      name: preview
      url: ${{ steps.deploy.outputs.preview-url }}
    steps:
      - name: git-checkout
        uses: actions/checkout@v3

      - uses: dtolnay/rust-toolchain@nightly
      - uses: Swatinem/rust-cache@v2
      - uses: jetli/trunk-action@v0.4.0
      - name: Build
        run: |
          cargo build --verbose
          rustup target add wasm32-unknown-unknown
          trunk build
      - name: Preview Deploy
        id: deploy
        uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          github-comment: true
          working-directory: ./dist

2. Merge to main - Action to build and deploy to prod. This will also create a production environment for your repo.

name: Release

on:
  push:
    branches:
      - main
env:
  CARGO_TERM_COLOR: always
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  Deploy-Production:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: git-checkout
        uses: actions/checkout@v3

      - uses: dtolnay/rust-toolchain@nightly
      - uses: Swatinem/rust-cache@v2
      - uses: jetli/trunk-action@v0.4.0
      - name: Trunk Build
        run: |
          rustup target add wasm32-unknown-unknown
          trunk build

      - name: Install Vercel CLI
        run: npm install --global vercel@latest
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        working-directory: ./dist
        run: vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}

[azriel91]

Heya, I've experimented building applications using leptos as a frontend in two modes:

• As a web server binary -- "the normal usage"
• As a subcommand, e.g. cli_tool web, similar to git instaweb which serves the current repository through a web interface.

This means having separate entry points for CLI, web server binary, and client:

• "cli", "ssr", "csr" top level features in Cargo.toml for each entry point.
• Different entry points in main.rs to switch between each mode.
• cargo build --features "cli" and cargo leptos build .. should work as usual, see ci.yml

I've only roughly experimented -- the CLI app still looks for LEPTOS_* environment variables; I suspect developers would want to automatically embed the values from Cargo.toml into the application when shipping.

[jggc]

I am currently re-writing our company website with Leptos, we are building a distributed cloud so deployment is one of our main things, but we have a tendency to use lower end deployment options. I'll post more details once the deployment is done, I don't know yet how exactly I will deploy it but probably one of those two options :

• Static website client side rendering on an S3 bucket backed by Ceph/Rados
• Kubernetes deployment with SSR

In the meantime, I'm very much open to provide feedback and thoughts on anything related to deploying various types of Rust apps.

We're also interested in providing early adopter hosting to get feedback.

[SilenLoc]

my playground https://github.com/SilenLoc/outcall is on gh pages.

With trunk, tailwind, latest leptos nightly and leptos-struct-table = "0.2.1"

https://silenloc.github.io/outcall/

see also the workflow and the Trunk.toml

you can also copy paste the whole thing to create an example repo under leptos

[eaglesemanation]

Hey, I have a slightly unconventional deployment, which is kind of still in progress, but at least it already works. I've deployed leptos project on to a Raspberry Pi with help of Buildroot (bunch of makefiles and scripts that allow to cross compile full Linux image)
Here is what I had to do:

Buildroot patches

Right now Buildroot has support for building rust packages with cargo, but I had to fix 2 issues:

1. It comes with Rust 1.68.2, and I wanted to use nightly features
2. It only installs toolchains for compiling for host and for target, I had to add WASM support

Here are changes that fix both of those issues on my fork: buildroot/buildroot@master...eaglesemanation:spectrometer_buildroot:2023.05-rust-wasm

Packages out of Buildroot tree

Official documentation explains this step here: https://buildroot.org/downloads/manual/manual.html#outside-br-custom
TLDR: There is a way to keep custom packages out of Buildroot tree, all you need to do is to create external.desc, external.mk and Config.in. Then you can add new packages into package/ directory

Creating makefile for leptos project

Essentially you can follow official docs for cargo packages with slight modifications:

1. We need to modify build step to execute wasm-pack as well. This probably should've been done as part of post build hook, but instead I've replaced build commands using this:

# Default build command + WASM build step
define PKGNAME_BUILD_CMDS
	cd $(PKGNAME_SRCDIR) && \
	$(TARGET_MAKE_ENV) \
		$(TARGET_CONFIGURE_OPTS) \
		$(PKG_CARGO_ENV) \
		$(PKGNAME_CARGO_ENV) \
		cargo build \
			$(if $(BR2_ENABLE_DEBUG),,--release) \
			--offline --manifest-path Cargo.toml --locked \
			--no-default-features --features=ssr
	cd $(PKGNAME_SRCDIR) && \
	$(TARGET_MAKE_ENV) \
		$(TARGET_CONFIGURE_OPTS) \
		$(PKG_CARGO_ENV) \
		$(PKGNAME_CARGO_ENV) \
		wasm-pack build \
			--out-dir pkg --target web \
			$(if $(BR2_ENABLE_DEBUG),--dev,--release) \
			-- \
			--offline --manifest-path Cargo.toml --locked \
			--no-default-features --features=hydrate
	cd $(PKGNAME_SRCDIR) && \
		tailwindcss --input style/input.css --output style/output.css
endef

2. After building WASM and CSS we need to manually copy stuff to some appropriate location on target FS. Here is what I did:

# cargo-package uses `cargo install`, which only installs binaries. Copy WASM manually 
define PKGNAME_INSTALL_WASM
	$(Q)mkdir -p $(TARGET_DIR)/usr/share/pkgname/pkg
	$(Q)cp -r $(PKGNAME_SRCDIR)/pkg $(TARGET_DIR)/usr/share/pkgname/
	find $(TARGET_DIR)/usr/share/pkgname/pkg/ -type f -exec sed -Ei 's/([a-zA-Z_]+)_bg.wasm/\1.wasm/p' {} \;
	for bg_file in $(TARGET_DIR)/usr/share/pkgname/pkg/*_bg*; do \
		fixed_file="$$(echo $$bg_file | sed -En 's/(.*)_bg(.*)/\1\2/p')" ; \
		mv $$bg_file $$fixed_file ; \
	done
	$(Q)cp $(PKGNAME_SRCDIR)/style/output.css $(TARGET_DIR)/usr/share/pkgname/pkg/pkgname.css
endef
PKGNAME_POST_BUILD_HOOKS += PKGNAME_INSTALL_WASM

3. I'm not exactly sure if this part is needed, but it seems like building ssr and hydrate separately requires a manual way to synchronize server function naming, and that's done through SERVER_FN_OVERRIDE_KEY. If my understanding is correct, that this can be done by adding this line, later I want to replace it with some actually random number decided at build time:

# Randomly generated number, needs to be consistent across ssr and hydrate packages
PKGNAME_CARGO_ENV += SERVER_FN_OVERRIDE_KEY='8306904707'

4. If someone wants to run Buildroot in a Nix shell - there is an annoying issue while linking to -latomic, which can be solved by setting target LDFLAGS to -L$(TARGET_DIR)/lib -Wl,-rpath,$(TARGET_DIR)/lib

I don't have a lot of experience of writing docs, and my explanation seems haphazard to me, so if someone wants to read through actual code, rather than my interpretation, it can be found here: https://github.com/eaglesemanation/spectrometer_utils/tree/main/sbc_config

[lalanikarim]

My current deployment flow involves cross-compiling to x86_64-unknown-linux-musl target so that there are no glibc-related issues on the server.

1. Make sure you have musl cross compilation binaries
   On Linux (use appropriate package manager and package name for musl-dev equivalent)

sudo apt install musl-dev

or on Mac (tested on M2)

brew install musl-cross

1.a. Optional on Macs
Add the below to ~/.cargo/config

[target.x86_64-unknown-linux-musl]
linker = "x86_64-linux-musl-gcc"

2. Cross compile with cargo leptos

TARGET_CC=x86_64-linux-musl-gcc LEPTOS_BIN_TARGET_TRIPLE=x86_64-unknown-linux-musl cargo leptos build -r

3. Create an archive for necessary artifacts for deployment

mkdir deploy/app
cp target/server/x86_64-unknown-linux-musl/release/portrait-booth deploy/app/
cp -r target/site deploy/app/
cp Cargo.toml deploy/app/
cd deploy
tar cvf app.tar app
gzip app.tar

4. On the server, assuming that the archive is extracted at /app and the application will be launched from within that directory, export the following env variables:

LEPTOS_OUTPUT_NAME=<output-name from [package.metadata.leptos]>
LEPTOS_SITE_ROOT=site

5. Launch the application from within the /app folder.

I also have a dockerfile in the works that might be useful when deploying within a container or to Kubernetes.

[srid]

Maybe Nix can help? I've nixified the development environment: https://github.com/srid/start-axum/tree/nixify

However I couldn't package the app (nix build). The challenge is that cargo leptos build doesn't work well with the crane builder. Can we build a leptos app using pure cargo build? If so, how?

cc @benwis (see he opened NixOS/nixpkgs#215400)

[benwis]

https://github.com/srid/start-axum/tree/nixify

I'm always happy to see more Nix in here. I actually have a Crane build deployment routine for some of my Leptos sites, so I know it can work. It's a bit clunky since I haven't updated it since cargo-leptos moved into nixpkgs main

[srid]

(N/m; fixed by changing version of wasm-bindgen in Cargo.toml

I can't use `cargo-leptops` from nixpkgs, because it leads to this error in the `start-axum` template,

       it looks like the Rust project used to create this wasm file was linked against
       version of wasm-bindgen that uses a different bindgen format than this binary:
       
         rust wasm file schema version: 0.2.87
            this binary schema version: 0.2.84
       
       Currently the bindgen format is unstable enough that these two schema versions
       must exactly match. You can accomplish this by either updating the wasm-bindgen
       dependency or this binary.

(My start-axum fork uses Rust nightly which it seems to require)

I actually have a Crane build deployment routine for some of my Leptos sites

Do you happen to have the Nix source available publicly?

[benwis]

Ya, Forgive the roughness, but here it is: https://github.com/benwis/benwis_leptos/blob/main/flake.nix Let me know if you see any improvements.

…

-Ben

------- Original Message -------

On Saturday, July 1st, 2023 at 8:35 AM, Sridhar Ratnakumar ***@***.***> wrote: I can't use cargo-leptops from nixpkgs, because it leads to this error in the start-axum template, it looks like the Rust project used to create this wasm file was linked against version of wasm-bindgen that uses a different bindgen format than this binary: rust wasm file schema version: 0.2.87 this binary schema version: 0.2.84 Currently the bindgen format is unstable enough that these two schema versions must exactly match. You can accomplish this by either updating the wasm-bindgen dependency or this binary. (My start-axum fork uses Rust nightly which it seems to require) > I actually have a Crane build deployment routine for some of my Leptos sites Do you happen to have the Nix source available publicly? — Reply to this email directly, [view it on GitHub](#1152 (comment)), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/ABVBTCMUGUSSCLOXQPYHWKDXOA7V7ANCNFSM6AAAAAAY3WY264). You are receiving this because you were mentioned.Message ID: ***@***.***>

[sebadob]

I am deploying everything as containers, all the time.

I built Dockerfiles for building either a gnu or a musl version of a leptos app in full ssr mode.

The files are multi stage and try to be as secure as possible by default.
I always use a "builder" image, which has all the necessary tools installed, to have faster and more efficient pipelines.

Builder Files

These builder files usually only need a rebuild when you want to upgrade to a new rust or cargo-leptos version. Otherwise they can be re-used all the time, which speeds up the final build process.

GNU

Filename: Dockerfile.builder-gnu

FROM rust:1.70-bullseye

RUN apt update && \
    apt install -y binaryen npm protobuf-compiler libssl-dev pkg-config musl-tools \
    && rm -rf /var/lib/apt/lists/*

RUN rustup target add wasm32-unknown-unknown
RUN rustup component add clippy

RUN cargo install cargo-generate
RUN cargo install cargo-leptos
RUN cargo install wasm-opt
RUN npm install -g sass

WORKDIR /work

CMD /bin/bash

Build with:

docker build -t leptos-builder-gnu -f Dockerfile.builder-gnu .

MUSL

Filename: Dockerfile.builder-musl

FROM rust:1.70-alpine3.18

RUN apk update && \
    apk add --no-cache bash binaryen gcc git g++ libc-dev make npm openssl-dev protobuf-dev protoc

RUN rustup target add wasm32-unknown-unknown
RUN rustup component add clippy

RUN cargo install cargo-generate
RUN cargo install cargo-leptos
RUN npm install -g sass

WORKDIR /work

CMD /bin/bash

Build with:

docker build -t leptos-builder-musl -f Dockerfile.builder-musl .

App Dockerfile

I usually have everything in one file and out-comment the necessary FROM sections depending on if I want a gnu or musl image.

# Chose the builder image
# `gnu` is the default target for rust but needs a specific version of GLIBC on the target system
# `musl` is the way smaller one which only need the linux kernel
#
# note: you may need to adopt the image in the 2nd stage down below, if you change this
#FROM leptos-builder-gnu AS builder
FROM leptos-builder-musl AS builder

# I usually do testing with a real database deployed somewhere in the network
ARG TEST_ENV_IP=192.168.220.21
ENV DATABASE_URL="postgresql://localdev:123SuperSafe@$TEST_ENV_IP:5432/localdev"

WORKDIR /work

# IMPORTANT: have a `.dockerignore` file and exclude at least your `target`
# directory to not copy huge amounts of data into the docker context
#
# !!! EVEN MORE IMPORTANT !!!
# If you have any secrets in a `.env` file or something, add this to `.dockerignore` too!
COPY . .

# this small workaround fixes a chicken and egg problem with `rust_embed` in this template
# so we can check clippy before actually compiling
RUN mkdir -p target/site
# make sure we exit early if clippy is not happy
RUN cargo clippy -- -D warnings

# execute tests first
RUN cargo leptos test

# after successful tests, build it
RUN cargo leptos build --release

########################################
########################################
########################################

# If you want to be able to debug the image later and `exec` into the container,
# change this line to alpine instead of scratch. This should only be done for
# debugging / testing, since scratch is way more secure.
FROM scratch as app
#FROM alpine:3.18.2 as app

# use this image instead of one from below, if you are using the `leptos-builder-gnu`
# as your `builder` in stage 1
#FROM gcr.io/distroless/cc:debug

# Must match your `output-name` from the `metadata.leptos` until the next release
ENV LEPTOS_OUTPUT_NAME=leptos-axum-template
ENV LEPTOS_SITE_ROOT=site
ENV LEPTOS_SITE_PKG_DIR=pkg
ENV LEPTOS_SITE_ADDR="0.0.0.0:3000"
ENV LEPTOS_RELOAD_PORT=3001

USER 10001

WORKDIR /app

COPY --chown=10001:10001 --from=builder /work/target/site/ ./site/
COPY --chown=10001:10001 --from=builder /work/target/server/release/server .

# depends on the port you choose
EXPOSE 3000

# must match your final server executable name
ENTRYPOINT ["/app/server"]

These files may use --build-args from the outside if necessary.

If you need some Kubernetes definitions, I could provide some if necessary. I do have quite a bit of documentation already created for another project: https://sebadob.github.io/rauthy/getting_started/k8s.html#create-and-apply-the-stateful-set

[ivancernja]

Hello everyone,

There's been quite some discussion as part of our community in getting Leptos support at Shuttle. As part of this conversation, I'd like to share the Leptos Starter Template one of our paid open source contributors created, which includes deployment options along with other integrations -- https://github.com/joshua-mo-143/leptos_axum_shuttle_ex

For context, Shuttle is a Rust-native cloud development platform that let's you quickly deploy your Rust apps. On top of that, it utilizes Infrastructure from Code which allows you to provision resources just by annotating your code.

Our Leptos Starter Template demonstrates an integration of TailwindCSS with the Leptos web framework, Axum support, and utilizes Trunk. With Shuttle on-top of it, deploying is just a matter of running the deploy command.

While the template is not in its final form yet, it is usable and provides clear instructions on getting started.

We believe that this template has the potential to help developers kickstart their Leptos projects and make deployment a smoother process.

We are very open to collaborating on ensuring a smooth Leptos deployment experience both for our users and Leptos users so thoughts & comments are appreciated! :)