Skip to content

Commit

Permalink
docs: added docker deployment docs (#98)
Browse files Browse the repository at this point in the history
* Add Docker deployment docs

* Apply all requested changes

* Add newlines to the markup of docker deployment docs
  • Loading branch information
phaleth authored Jan 2, 2022
1 parent c2de025 commit 93f2c4b
Show file tree
Hide file tree
Showing 4 changed files with 524 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/0.3.x/en-US/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@
- [Serverless Deployment](/docs/deploying/serverless)
- [Optimizing Code Size](/docs/deploying/size)
- [Relative Paths](/docs/deploying/relative-paths)
- [Docker Deployment](/docs/deploying/docker)
- [Migrating from v0.2.x](/docs/updating)
- [Common Pitfalls and Known Bugs](/docs/pitfalls-and-bugs)

Expand Down
261 changes: 261 additions & 0 deletions docs/0.3.x/en-US/deploying/docker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,261 @@
# Docker Deployment

For situations where [serverful deployment](:deploying/serverful) is required, or in case there is a need to deploy one of the examples found on GitHub without prior setup of all necessary dependencies, below are `Dockerfile` examples meant to serve for different deployment scenarios. These steps can also serve as guidelines for production deployments.

Note that the following examples should be modified for your particular use-case rather than being used as-is. Also, these `Dockerfile`s are standalone because they use `curl` to download examples directly from the Perseus repository (of course, you'll probably want to use your own code in production).

Before proceeding with this section, you should be familiar with Docker's [multi-stage builds system](https://docs.docker.com/develop/develop-images/multistage-build) and Perseus' [code size optimizations](:deploying/size).

<details>
<summary>Production example using the size optimizations plugin</summary>

# get the base image
FROM rust:1.57-slim AS build

# install build dependencies
RUN apt update \
&& apt install -y --no-install-recommends lsb-release apt-transport-https \
build-essential curl wget

# vars
ENV PERSEUS_VERSION=0.3.0 \
PERSEUS_SIZE_OPT_VERSION=0.1.7 \
ESBUILD_VERSION=0.14.7 \
BINARYEN_VERSION=104

# prepare root project dir
WORKDIR /app

# download the target for wasm
RUN rustup target add wasm32-unknown-unknown

# install wasm-pack
RUN cargo install wasm-pack

# retrieve the src dir
RUN curl https://codeload.github.com/arctic-hen7/perseus-size-opt/tar.gz/main | tar -xz --strip=2 perseus-size-opt-main/examples/simple

# go to src dir
WORKDIR /app/simple

# install perseus-cli
RUN cargo install perseus-cli --version $PERSEUS_VERSION

# clean and prep app
RUN perseus clean && perseus prep

# specify deps in app config
RUN sed -i s"/perseus = .*/perseus = \"${PERSEUS_VERSION}\"/" ./Cargo.toml \
&& sed -i s"/perseus-size-opt = .*/perseus-size-opt = \"${PERSEUS_SIZE_OPT_VERSION}\"/" ./Cargo.toml \
&& cat ./Cargo.toml

# modify lib.rs
RUN sed -i s'/SizeOpts::default()/SizeOpts { wee_alloc: true, lto: true, opt_level: "s".to_string(), codegen_units: 1, enable_fluent_bundle_patch: false, }/' ./src/lib.rs \
&& cat ./src/lib.rs

# run plugin(s) to adjust app
RUN perseus tinker \
&& cat .perseus/Cargo.toml \
&& cat ./src/lib.rs

# single-threaded perseus CLI mode required for low memory environments
#ENV PERSEUS_CLI_SEQUENTIAL=true

# deploy app
RUN perseus deploy

# go back to app dir
WORKDIR /app

# download and unpack esbuild
RUN curl -O https://registry.npmjs.org/esbuild-linux-64/-/esbuild-linux-64-${ESBUILD_VERSION}.tgz \
&& tar xf esbuild-linux-64-${ESBUILD_VERSION}.tgz \
&& ./package/bin/esbuild --version

# run esbuild against bundle.js
RUN ./package/bin/esbuild ./simple/pkg/dist/pkg/perseus_engine.js --minify --target=es6 --outfile=./simple/pkg/dist/pkg/perseus_engine.js --allow-overwrite \
&& ls -lha ./simple/pkg/dist/pkg

# download and unpack binaryen
RUN wget -nv https://github.com/WebAssembly/binaryen/releases/download/version_${BINARYEN_VERSION}/binaryen-version_${BINARYEN_VERSION}-x86_64-linux.tar.gz \
&& tar xf binaryen-version_${BINARYEN_VERSION}-x86_64-linux.tar.gz \
&& ./binaryen-version_${BINARYEN_VERSION}/bin/wasm-opt --version

# run wasm-opt against bundle.wasm
RUN ./binaryen-version_${BINARYEN_VERSION}/bin/wasm-opt -Os ./simple/pkg/dist/pkg/perseus_engine_bg.wasm -o ./simple/pkg/dist/pkg/perseus_engine_bg.wasm \
&& ls -lha ./simple/pkg/dist/pkg

# prepare deployment image
FROM debian:stable-slim

WORKDIR /app

COPY --from=build /app/simple/pkg /app/

ENV HOST=0.0.0.0

CMD ["./server"]

</details>

<details>
<summary>Production examples using `wee_alloc` manually</summary>

# get the base image
FROM rust:1.57-slim AS build

# install build dependencies
RUN apt update \
&& apt install -y --no-install-recommends lsb-release apt-transport-https \
build-essential curl wget

# vars
ENV PERSEUS_VERSION=0.3.0 \
WEE_ALLOC_VERSION=0.4 \
ESBUILD_VERSION=0.14.7 \
BINARYEN_VERSION=104

# prepare root project dir
WORKDIR /app

# download the target for wasm
RUN rustup target add wasm32-unknown-unknown

# install wasm-pack
RUN cargo install wasm-pack

# retrieve the src dir
RUN curl https://codeload.github.com/arctic-hen7/perseus/tar.gz/v${PERSEUS_VERSION} | tar -xz --strip=2 perseus-${PERSEUS_VERSION}/examples/tiny

# go to src dir
WORKDIR /app/tiny

# install perseus-cli
RUN cargo install perseus-cli --version $PERSEUS_VERSION

# specify deps in app config
RUN sed -i s"/perseus = .*/perseus = \"${PERSEUS_VERSION}\"/" ./Cargo.toml \
&& sed -i "/\[dependencies\]/a wee_alloc = \"${WEE_ALLOC_VERSION}\"" ./Cargo.toml \
&& cat ./Cargo.toml

# modify and prepend lib.rs
RUN echo '#[global_allocator] \n\
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; \n\
' | cat - ./src/lib.rs > ./src/lib.rs.tmp \
&& mv ./src/lib.rs.tmp ./src/lib.rs \
&& cat ./src/lib.rs

# clean, prep and eject app
RUN perseus clean && perseus prep && perseus eject

# adjust and append perseus config
RUN sed -i s"/perseus = .*/perseus = \"${PERSEUS_VERSION}\"/" .perseus/Cargo.toml \
&& echo ' \n\n\
[profile.release] \n\
codegen-units = 1 \n\
opt-level = "s" \n\
lto = true ' >> .perseus/Cargo.toml \
&& cat .perseus/Cargo.toml

# single-threaded perseus CLI mode required for low memory environments
#ENV PERSEUS_CLI_SEQUENTIAL=true

# deploy app
RUN perseus deploy

# go back to app dir
WORKDIR /app

# download and unpack esbuild
RUN curl -O https://registry.npmjs.org/esbuild-linux-64/-/esbuild-linux-64-${ESBUILD_VERSION}.tgz \
&& tar xf esbuild-linux-64-${ESBUILD_VERSION}.tgz \
&& ./package/bin/esbuild --version

# run esbuild against bundle.js
RUN ./package/bin/esbuild ./tiny/pkg/dist/pkg/perseus_engine.js --minify --target=es6 --outfile=./tiny/pkg/dist/pkg/perseus_engine.js --allow-overwrite \
&& ls -lha ./tiny/pkg/dist/pkg

# download and unpack binaryen
RUN wget -nv https://github.com/WebAssembly/binaryen/releases/download/version_${BINARYEN_VERSION}/binaryen-version_${BINARYEN_VERSION}-x86_64-linux.tar.gz \
&& tar xf binaryen-version_${BINARYEN_VERSION}-x86_64-linux.tar.gz \
&& ./binaryen-version_${BINARYEN_VERSION}/bin/wasm-opt --version

# run wasm-opt against bundle.wasm
RUN ./binaryen-version_${BINARYEN_VERSION}/bin/wasm-opt -Os ./tiny/pkg/dist/pkg/perseus_engine_bg.wasm -o ./tiny/pkg/dist/pkg/perseus_engine_bg.wasm \
&& ls -lha ./tiny/pkg/dist/pkg

# prepare deployment image
FROM debian:stable-slim

WORKDIR /app

COPY --from=build /app/tiny/pkg /app/

ENV HOST=0.0.0.0

CMD ["./server"]

</details>

<details>
<summary>Test example for deploying a specific branch from the Perseus repository</summary>

# get the base image
FROM rust:1.57-slim AS build

# install build dependencies
RUN apt update \
&& apt install -y --no-install-recommends lsb-release apt-transport-https \
build-essential curl

# vars
ENV PERSEUS_BRANCH=main

# prepare root project dir
WORKDIR /app

# download the target for wasm
RUN rustup target add wasm32-unknown-unknown

# install wasm-pack
RUN cargo install wasm-pack

# install bonnie
RUN cargo install bonnie

# retrieve the branch dir
RUN curl https://codeload.github.com/arctic-hen7/perseus/tar.gz/${PERSEUS_BRANCH} | tar -xz

# go to branch dir
WORKDIR /app/perseus-${PERSEUS_BRANCH}

# install perseus-cli from branch
RUN bonnie setup

# clean app
RUN bonnie dev example tiny clean

# go to the branch dir
WORKDIR /app/perseus-${PERSEUS_BRANCH}

# single-threaded perseus CLI mode required for low memory environments
#ENV PERSEUS_CLI_SEQUENTIAL=true

# deploy app
RUN bonnie dev example tiny deploy

# move branch dir
RUN mv /app/perseus-${PERSEUS_BRANCH} /app/perseus-branch

# prepare deployment image
FROM debian:stable-slim

WORKDIR /app

COPY --from=build /app/perseus-branch/examples/tiny/pkg /app/

ENV HOST=0.0.0.0

CMD ["./server"]

</details>
1 change: 1 addition & 0 deletions docs/next/en-US/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@
- [Serverless Deployment](/docs/deploying/serverless)
- [Optimizing Code Size](/docs/deploying/size)
- [Relative Paths](/docs/deploying/relative-paths)
- [Docker Deployment](/docs/deploying/docker)
- [Migrating from v0.2.x](/docs/updating)
- [Common Pitfalls and Known Bugs](/docs/pitfalls-and-bugs)

Expand Down
Loading

0 comments on commit 93f2c4b

Please sign in to comment.