Ubuntu tutorial
This will is a tutorial explaining how to setup Empirica an Ubuntu 23.10 Droplet on Digital Ocean.
Last updated
Was this helpful?
This will is a tutorial explaining how to setup Empirica an Ubuntu 23.10 Droplet on Digital Ocean.
Last updated
Was this helpful?
This will go through all the steps needed to deploy an Empirica experiment in a generally secure manner, how to update your experiment, and how to retrieve your data. We are using Digital Ocean, which is relatively easy to use, but you can use any hosting provider and the steps will be similar if you use Ubuntu 22+.
This tutorial does assume a few things:
You have minimal Linux, command line, and ssh experience. If you don't check out some quick intro tutorials on Youtube.
You have a domain name. A subdomain on empirica.app can be provided, see Setup your domain below for details.
At the root of your experiment, run:
This will create a file called myexperiment.tar.zst where myexperiment is the name of your experiment or empirca. This file will be useful later in the process.
Sign up to
Click Create in the top left, then Droplets
Choose a region close to you ; datacenter doesn't matter much, leave the default
For the image selection, choose Ubuntu then 23.10 x64
For size, choose Basic, then Premium AMD, then 4GB/2CPU or 8GB/4CPU depending on your needs. Generally, you can get by with 2 CPUs, espcially during development, and you can always upgrade your droplet later.
Enable automated backup..., daily, doesn't hurt
For SSH keys, if you know what's up, add your key, if you don't, follow .
Enable Add improved metrics...
Quantity: 1
Hostname: you choose (e.g. myexperiment), this is unrelated to your domain name, it's mostly just the name in your Digital Ocean admin UI.
Click Create Droplet
Wait for the Droplet to start, and note down the IP address
If you have a access to a domain name, we'll assume you know how to setup an A Record (name is the domain or subdomain name you want to use, the value is the IP address of your Droplet, and for TTL either automatic/default, or 5 min if you expect to change the address soon).
You might want to double check your domain is configured correctly (it can take a few minutes to propagate). On macos and linux you can use dig:
If you do not have a domain name, you can contact Nicolas P. on Slack with the subdomain on empirica.app you'd like to use (e.g. mycoolexperiment.empirica.app). Please provider 2-3 options that are not too generic (e.g. experiment is too generic) so we don't conflict, and the IP address of your Droplet.
A couple of notes:
please do not do anything illegal on your domain. We are not responsible for anything sketchy you do on your subdomain
if you're taking down your experiment, please let us know so we can cleanup the DNS entry. We reserve the right to clear the subdomain if we haven't heard from your in a year or two
SSH into your server using the IP address from your Droplet. For example:
To install empirica on your server, run:
Caddy is the reverse proxy that will enable HTTPS on your experiment. To install, run the following commands:
We want Empirica to reload automatically in case of a crash, a server restart, or an update. For that we will create a few folders and configuration files.
First, create a folder for the deployment at the root of your user (where you ssh-ed in). We will use a directory called empirica:
We will create 2 files to start and restart empirica using systemctl. First, run:
In this file, paste the following:
Save the file (with nano, ctrl+o then Enter) and exit (ctrl+x).
We will then create a restarter file:
And paste the following:
We will then create a watcher file:
And paste the following:
Save and exit nano. This file will restart empirica when the empirica bundle changes.
Run the following to register these 2 files:
Next, we'll upload your Empirica experiment bundle (the .tar.zst file we created in the first step) from your machine to your server. You can do that with scp (replace myexerpiment with the name of your bundle and the IP address with your Droplet IP address):
We can now start empirica like so:
Check that it's running as expected:
It should return a bunch of html with an HTTP code 200 (HTTP/1.1 200 OK).
Delete the existing configuration for Caddy:
And add a new one:
With the following, where the domain name if the domain name you setup:
And restart caddy:
It might take a minute for the HTTPS certificates to generate. Go to your domain in your browser, and if all goes well, your experiment is deployed, with HTTPS.
We will enable our restarter units:
Now, next time you bundle and upload again, empirica should restart automatically. See Update your experiment below.
Go to /admin on your domain in the browser. You will be asked for a username and password. You can find the default username (admin by default) and password (randomly generated with your new project) in your project in .empirica/empirica.toml on your local machine. You can change or add more users from that file and redeploy.
On your server, the data will be in ~/empirica, and you can run the following from root:
To copy the data back to your machine, you can run, from your machine (* will pull all the exports, you can specify the exact zip file your want instead) :
To update your experiment, bundle and scp again from your local machine:
You will need to reload the browser to see the changes. It does not reload the page automatically as it does in local development mode.