---
title: "Alternative strategies for deploying workflowr websites"
subtitle: "workflowr version `r utils::packageVersion('workflowr')`"
author: "John Blischak"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Alternative strategies for deploying workflowr websites}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

The [Getting Started vignette][vig-getting-started] provides instructions for
deploying the workflowr website using the service [GitHub Pages][gh-pages]
because it is quick and convenient. However, the static website created by
workflowr can be deployed using any strategy you like. Below are instructions
for deploying the workflowr website contributed by other workflowr users. If you
would like to contribute instructions for another deployment strategy, please
fork the [workflowr repository][workflowr] on GitHub and add your instructions
to this file. If you need any assistance with this, please
don't hesitate to open an [Issue][wflow-issues].

[gh-pages]: https://pages.github.com/
[vig-getting-started]: wflow-01-getting-started.html
[wflow-issues]: https://github.com/workflowr/workflowr/issues
[workflowr]: https://github.com/workflowr/workflowr

## Amazon S3 (password-protected)

Another way to privately share your workflowr site is by uploading it to [Amazon
S3][s3]. S3 is an object storage service for the Amazon cloud, and can be used
to host static websites. Basic HTTP authentication can be accomplished using
[CloudFront][cloudfront], Amazon's content delivery network, and
[Lamba@Edge][lambda], which enables the execution of serverless functions to
customize content delivered by the CDN. This [blog post][hackernoon] goes into
more detail about what that all means. A more detailed guide to setting up the
bucket is [here][kynatro]. Some templates for scripting the process are
[here][dumrauf].

Contributed by E. David Aja ([edavidaja][]).

[cloudfront]: https://aws.amazon.com/cloudfront/
[edavidaja]: https://github.com/edavidaja
[dumrauf]: https://github.com/dumrauf/serverless_static_website_with_basic_auth
[hackernoon]: https://hackernoon.com/serverless-password-protecting-a-static-website-in-an-aws-s3-bucket-bfaaa01b8666
[kynatro]: https://kynatro.com/blog/2018/01/03/a-step-by-step-guide-to-creating-a-password-protected-s3-bucket/
[lambda]: https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html
[s3]: https://aws.amazon.com/s3/

## Beaker Browser (secure sharing)

If your project contains sensitive data that prevents you from publicly sharing
the results, one alternative option is to self-host your workflowr website using
[Beaker Browser][beaker].

[Beaker Browser][beaker] allows website creation, cloning, modification, and
publishing locally. After the site is ready, hitting "share" produces a unique
[Dat project dat://][dat] hyperlink, for example:

    dat://adef21aa8bbac5e93b0c20a97c6f57f93150cf4e7f5eb1eb522eb88e682309bc

This dat:// link can then be shared and the site opened *all the while being
hosted locally on the site producer's machine.* The particular example above is
a site, produced in RStudio using workflowr, with placeholder content and R code
chunks, compiled as usual.

Security for your site is achieved with site encryption inherent in the Dat
protocol (see [Security][dat-security] on the [datproject docs page][dat-docs]),
as well as the obscurity of the unique link. Beaker Browser saves your
individual project sites in the folder `~/Sites`.

To create a Beaker Browser version of your workflowr site:

1. [Install][beaker-install] Beaker Browser and run it.
1. Select "New Site" in the three-bar dropdown menu found to the right of the
"omnibar" for web link entry, and enter its Title and (optional) a Description
of the site. This creates a folder in the Beaker Browser `~/Sites` directory
named for your Title, for example, "placeholder_workflowr", and populates the
folder with a `dat.json` file.
1. In the main Beaker Browser pane, use "Add Files" or "Open Folder" to copy the
entire contents of the workflowr `docs/` folder to your new Beaker Browser site
folder (see Symlink Synchronization, below).
1. Once copied, the new site is ready to go. Pressing "Share" in the main Beaker
Browser pane reveals the unique dat:// link generated for your Beaker Browser
site. Sharing this link with anyone running Beaker Browser will allow them to
access your workflowr HTML files...*directly from your computer*.

Instead of having to manually copy your workflowr `docs/` directory to your
Beaker Browser site directory, you can create a symlink from your workflowr
`docs/` directory to the Beaker Browser site directory. The line below links the
`docs/` directory of a hypothetical "workflowr-project" saved in `~/github/` to
the hypothetical Beaker `placeholder_workflowr` subdirectory:

    ln -s ~/github/workflowr-project/docs ~/Users/joshua/Sites/placeholder_workflowr

The direct-sharing nature of the above workflow means that the host computer
needs to be running for site access. Two alternative recommended by Beaker
Browser developer [Paul Frazee][pfrazee] are [hashbase.io][] and the Beaker
Browser subproject [dathttpd][]. While hosting Beaker Browser sites is outside
of the scope of this direct sharing paradigm, each of these options has
strengths. The former, hashbase.io (free account required), is a web-hosted
central location for dat:// -linked content, removing the need for the host
computer to be running. The latter dathttpd example is an additional
server/self-hosting option that can be used if desired.

This solution was contributed by [Josh Johnson][johnsonlab]. For more details,
please read his [blog post][johnsonlab-blog] and the discussion in Issue
[#59][].

[#59]: https://github.com/workflowr/workflowr/issues/59
[beaker]: https://beakerbrowser.com/
[beaker-install]: https://beakerbrowser.com/install/
[dat]: https://dat.foundation
[dat-docs]: https://docs.datproject.org/
[dat-security]: https://docs.datproject.org/docs/security-faq
[dathttpd]: https://github.com/beakerbrowser/dathttpd
[hashbase.io]: https://hashbase.io
[johnsonlab]: https://github.com/johnsonlab
[johnsonlab-blog]: https://johnsonlab.github.io/blog-post-22/
[pfrazee]: https://github.com/pfrazee

## GitLab Pages

To deploy your workflowr website with [GitLab Pages][gitlab], you can use the
function `wflow_use_gitlab()`. You can choose if the site is public or private.
For more details, please see the dedicated vignette [Hosting workflowr websites
using GitLab](wflow-06-gitlab.html).

[gitlab]: https://docs.gitlab.com/ee/ci/yaml/README.html#pages
