Comment on page

Deploy your web experiment

One you have a server setup with exbuilder deployer, deploying your exbuilder project to the web is fairly straightforward.

Deploy a new exbuilder project

Clone your project repository

Deploying a new exbuilder project to your server is a simple as cloning the repository. SSH into your server:
Note that if you haven't set up a user, you can instead login as root. This is usually frowned upon, but we won't tell on you. You can also go back and setup a user if you like.
And then clone your repository onto your server
git clone https://github.com/you/yourrepo.git

Configure environment

Next you'll set your environment variables to their deployment values. These are usually the same as in local development, except you'll change the variables used to configure the database to your deployment database (usually exbuilder deployer's database or an external database).

Copy the .env.sample file

From inside your project's directory on the server
cd yourproject
copy the sample .env file
cp .env.sample .env

Set your environment variables

Then, set your environment variables.
nano .env
If you are using the deployer's database deployer_db, you likely only need to change DB_PASSWORD and DB_SSLMODE . Also make sure you have a unique PROJECT_NAME, as exbuilder uses this to name your containers.
# name of your project;
PROJECT_NAME=your-project-name # make sure to change to yours
# configure your database;
DB_HOST = postgres
DB_PORT = 5432
DB_NAME = exbuilder
DB_USER = exbuilder
DB_PASSWORD = password # change this one to something secure that you'll remember
DB_SSLMODE = disable # change this to require

Start your project's deploy containers

Starting the deployment containers works almost the same as starting the development containers, except for one very important part: you have to specifically request that docker use the docker-compose.deploy.yml file. To do this, run docker-compose up -d --build, but add an -f flag after docker-compose to tell docker to use the deploy file:
docker-compose -f docker-compose.deploy.yml up -d --build
Great! You can check that your container is running with
docker ps

Configure nginx proxy manager

Now that your containers are running, you need a way for users to request this container when they visit your website. You'll do this with deployer's ngingxproxymanager

Add proxy host with SSL cert

Because you are running your project's container on the exbuilder_deployer docker network (the docker-compose.deploy.yml file is setup to do this), you can select Add proxy host, and add a subdomain of your choice (e.g. project1.yourwebsite.com).
Then, select http as the Scheme and use yourprojectname_nginx(the name of your project's nginx docker container on the exbuilder_deployer network) as the Forward Hostname . You'll also need to choose 8080 as the Forwarding Port (the port that container is listening on) and toggle on Block Common Exploits.
Add proxy host
Before you save, you can secure things a bit more by navigating to the SSL tab to obtain an SSL cert for this subdomain. Select Request a new SSL Certificate and then toggle on: Force SSL, HTTP/2 Support, and HSTS Enabled. Enter your email address and toggle on I Agree to the Let's Encrypt Terms of Service. Then save your new proxy host!
Request SSL certificate
Check that it works by visiting the subdomain project1.yourwebsite.com, or whatever subdomian you used. You should arrive at your exbuilder landing page! That's it! You are ready to collect data.
You may want to double check that your project is writing to the deployer_db before you send your experiment to participants!

Update existing exbuilder projects

If your exbuilder project is already deployed to your server and you need to make changes, you should (1) make the changes to your project code locally and test that it works, (2) push your changes to your repository, and then (3) pull those changes into the repository on your server.
From your project directory on the server:
git pull origin main
Be careful about doing this if your experiment is already deployed and collecting data. Best to ensure you are not collecting data when you make a change and make a note of the data/time you made the change for your records.

Remove exbuilder projects

If you want to remove an exbuilder project from your server, you need to

Stop the container

From inside your project directory on the server, run
docker-compose down

Remove the proxy and domain

If you won't need that subdomian anymore, you can remove it in your ngnixproxyhost with.

Optionally delete the files from your server

You can delete files with the following. You may need to include sudo .
rm -r yourprojectrepo