Documentation

Downloading Boutique (& Copying it to Your Server)

After purchase, you can download the Boutique binary to your computer from this website. Use scp to upload it to your server: 

local$ scp /path/to/downloads/boutique-linux-amd64 example.com:.
local$ ssh example.com
server$ sudo mkdir -p /usr/local/bin
server$ sudo cp boutique-linux-amd64 /usr/local/bin/boutique

Please make sure the /usr/local/bin directory is within your $PATH.

Creating a PostgreSQL Database

Make sure you have a user and database created for Boutique. The snippet below assumes you run have a deploy user that's used to run Boutique (or other web applications). It also creates a boutique database. 

$ sudo -u postgres createuser deploy
$ sudo -u postgres createdb boutique
$ sudo -u postgres psql
postgres=# alter user deploy with encrypted password 'secret';
postgres=# grant all privileges on database boutique to deploy;

Running `boutique --install`

Before you start the installation process, grab these values from Stripe and AWS:

After you've copied the binary onto your server, start the install process by running: 

$ boutique --install

You will be asked for the user running Boutique, the absolute path of Boutique, and the password for the Boutique admin panel. I suggest running Boutique as a non-root user for security, but it will also work if you use root.

Boutique will install the files /etc/systemd/system/boutique.service and /etc/systemd/system/boutiqueq.service. These will be used to start the Boutique server and queue anytime your server starts. Please double-check to make sure those files are correct.

Next, Boutique will install configuration files into the ~/.boutique directory. The application is scoped to whichever user you selected earlier. Whenever you run Boutique, make sure to run it as the installed user. You'll be asked to set some environment variables:

If you prefer to set environment variables a different way, you can comment out all lines in your Boutique config file.

Boutique will then generate the frontend assets (HTML, CSS, JavaScript, and images) and migrate your database.

Your admin credentials will be set to whatever email address you used to purchase Boutique and the password you entered earlier. If you ever need to reset them, just run boutique --reset.

Proxying via Nginx

You'll need to setup a web server to:

  1. point URL to /home/user/.boutique/public
  2. serve HTML and other asset files
  3. serve /admin/* requests to all point to the index.html file
  4. reverse proxy /api/* requests to the Boutique port

You can do that with Nginx or Apache. Here's an example on how to do that with Nginx: 

# /etc/nginx/sites-enabled/nginx-*.conf, inside server block
listen 443 ssl;
listen [::]:443 ssl;
server_name boutique.example.com;

# to remove trailing slash
rewrite ^(/.*)\.html(\?.*)?$ $1$2 permanent;
rewrite ^/([^.]*)/$ /$1 permanent;

# serve from this directory
root /home/deploy/.boutique/public;
index index.html;

# serve non-HTML asset files
location ~* \.(jpg|jpeg|png|css|js|eot|ttf|woff|woff2)$ {
  expires max;
  try_files $uri =404;
}

# reverse proxy API requests to port 3000
location ~ ^/api/.*$ {
  proxy_pass http://localhost:3000;
}

# catch all /admin/* routes and serve index.html file
location ~ ^/admin.*$ {
  try_files /index.html =404;
}

Starting and Stopping Boutique

Boutique systemd service files have been installed. To use them: 

# start Boutique
$ sudo service boutique start
$ sudo service boutiqueq start

# stop Boutique
$ sudo service boutique stop
$ sudo service boutiqueq stop

Setting up Stripe Webhooks

Boutique requires a Stripe webhook to verify purchases. To set it up:

  1. Go to the Stripe Webhooks Dashboard
  2. Click the "+ Add Endpoint" button
  3. For the "Endpoint URL", put https://boutique.example.com/api/webhook/purchases (be sure to replace with your domain)
  4. For "Events to Send", select "payment_intent.succeeded"
  5. Click "Add Endpoint"

Setting up AWS SES and SNS Webhooks

Boutique uses AWS SES to send emails and SNS to track email events (such as bounces and complaints). Any email you send from will need to be added to SES:

  1. Sign into your AWS Console
  2. In the top search bar, navigate to SES (Amazon Simple Email Service)
  3. In the left sidebar, navigate to "Email Addresses"
  4. Use the "Verify a New Email Address" and follow the steps for each email address you'll be sending from

You'll also need to setup SNS to call Boutique's webhook:

  1. Go to the AWS Console if you're not there yet
  2. In the top search bar, navigate to SNS (Amazon Simple Notification Service)
  3. In the left sidebar, click on "Topics"
  4. Click the "Create topic" button
  5. Select "Standard" for type and set the name to "boutique", click "Create topic" to finalize
  6. On the next page, click "Create subscription"
  7. Select HTTPS for the protocol and paste in https://boutique.exmaple.com/api/webhook/emails for the URL (be sure to replace with your domain)

Finally, you can connect SES to SNS via a configuration set. This is how AWS sends out notification on bounces, rejects, and complaints:

  1. Go to the AWS Console if you're not there yet
  2. In the top search bar, navigate to SES (Amazon Simple Email Service)
  3. In the left sidebar, navigate to "Configuration Sets"
  4. Click "Create Configuration Set" and create a set named "boutique"
  5. Click on the configuration set link to "boutique"
  6. Add destination to "SNS"
  7. Name it "boutique"
  8. Select event types: "Reject", "Bounce", "Complaint". If you want to track Open/Click, you can select those two also.
  9. For the Topic, select "boutique" (the topic you created earlier) and click "Save"

Getting Started with Boutique

After you've started boutique with service boutique start and service boutiqueq start, it should start running on whatever port you've designated. After configuring Nginx/Apache to reverse proxy to it, the admin panel should be available at: 

https://boutique.example.com/admin # remember to replace with your domain name!

Go ahead to /admin in your web browser. Log in with the email you used to purchase Boutique and the password you set at the beginning of installation.

Creating a Product

Products are what you'll sell to your customers. You can upload files, add URLs, or even tell Boutique to run a script on your server to generate a file. After purchase, customers will have access to your product.

From the Boutique admin panel, click on "Products" in the sidebar and click "Add Product":

To further configure your product, you can click "Edit Product" from the "Actions" menu in the top right corner.

Once you've created a product, it will create a "Base" option for you. A single product can have different tiers, like Base/Plus/Premium. Each tier can have different price points and attached files. These tiers are called options in Boutique. You can add more options on this tab, or go to the "Assets" tab to upload a file.

Assets are what your customer will download after they purchase your product. A single product can have zero or more assets. From the "Assets" tab, you can upload files or add a link for your customers. You can attach them to options via the "Options" tab.

When you're satisfied with your uploads, go to the "Install" tab. This will have instructions on how to install the purchase modal on your website.

Creating a Newsletter

Newsletters are what your audience can subscribe to. After subscribing, they'll receive all drip emails and future broadcasts.

From the Boutique admin panel, click on "Newsletters" in the sidebar and click "Add Newsletter":

Additional properties can be found from the "Actions" -> "Edit Product" menu item in the top right corner. The "Schedule" tab will determine when your drip emails are sent out, these time slots are for your subscribers' timezone. The "Email" tab will let you customize email content and colors.

On the main newsletter screen, you can add drip and broadcast emails via their respective tabs. Drip emails are pre-written sequences that are sent out to subscribers based on a delayed amount of days. Broadcast emails are sent immediately to all current subscribers.

Go to the "Install" tab for instructions on how to install the subscribe modal to your website.

Customizing the Embedded Modal

The embedded modal can be customized with Boutique.configure({ settings... });. For example: 

Boutique.configure({
  primaryColor: "#3f8efa",
  fontFamily: "sans-serif",
  fontSize: "15px",
  buyButton: "Purchase for {{price}}",
  recoverButton: "Resend Email",
  receiptHtml: "<p>Thank you! Your order was sent to {{email}}</p>",
  subscribeConfirmHtml: "<p>An email was sent to {{email}}, please click the confirmation link in it to subscribe.</p>"
});

Theme and general settings available are:

Product settings:

Newsletter settings:

Email Templates

Content on email templates are configurable using a subset of the Liquid Templating Language, and Markdown with pass-through HTML.

Emails such as purchase receipts or newsletter subscribe confirmation can be customized by:

  1. going to the product/newsletter page
  2. clicking the "Actions" menu in the top right corner, then clicking "Edit"
  3. select the "Email" tab
  4. select "Template" or "Receipt/Recover/Subscribe Email Content"

Check the help text for each field to see what placeholders are available for each email (for example {{price}} or {{name}}). If a placeholder includes HTML, be sure to run it through the | safe filter.

All Drip and Broadcast emails have access to these placeholders:

Forgot Your Password

If you ever forget your password, ssh into your server and change to your deploy user. Then run boutique --reset to reset your password.

It's important to change to your deploy user before using the boutique command, since all configuration is stored under their home directory.

Updating Boutique

You can get the latest version of Boutique from this site.

Once you've downloaded the latest binary: 

local$ scp /path/to/downloads/boutique-linux-amd64 example.com:.
local$ ssh example.com
server$ service boutique stop && service boutiqueq stop
server$ sudo cp boutique-linux-amd64 /usr/local/bin/boutique
server$ su deploy # change to whatever user runs Boutique
server$ boutique --migrate && boutique --generate
server$ service boutique start && service boutiqueq start

This will replace your current Boutique binary, restart the server/queue, run any updated database migrations, and generate new frontend assets (if any).

Backing Up Boutique

Backup the database used for Boutique and backup the ~/.boutique directory (located in the deploy user's home directory). 

$ pg_dump boutique > boutique_db.bak
$ su deploy
$ cd && tar cfz boutique_config.tgz .boutique

Other Questions

Please contact me if you have any questions about Boutique.