I previously wrote about using umami analytics where we needed a VPS, and we had to manage our own docker containers and database. But you can get other people to do that for you, and do it for free! That’s assuming you are allowed to use, and stay within, the free tier of PlanetScale, Vercel and GitHub.

Let’s get started.

Accounts #

To do any of this, you will need an account for PlanetScale, Vercel, and GitHub. Check the requirements of their free tiers, if you’re breaching then you’ll either lose the service or get charged money.

Database #

We’ll create our database first. PlanetScale doesn’t support foreign keys, so we’ll need to run a bootstrapping process first so umami can vibe with the database.

Create the database #

Just in case my instructions become stale, you can find the PlanetScale documentation on how to create a database here.

Log into PlanetScale.
Depending on where you land, click either create or Create your first database.
Name your database umami-db.
Choose your region - you’ll probably want to pick whichever is closest to you. I chose ap-southeast-2.
Click Create database.
Click Connect (If you can’t see that, click into the database you just made).
Click New password.
Enter a Name - something like vercel-application. Leave the Branch as main, and make sure the Role is Admin.
Click Create password. (Just in case, you might need to make sure you are Connect with Prisma.)
Copy the .env string somewhere safe - we’ll need it later. It has the DATABASE_URL which contains the username and password that the umami application will use to connect to the database.
It looks like this:
```
DATABASE_URL='mysql://fldn3vo06n:[email protected]/umami-db?sslaccept=strict'`
```

Now we’ve setup our database and we’ve got what we need to connect to it.

Forking umami #

Next we need to fork umami, clone it to our local machine, and setup some environment variables so we can connect to the PlanetScale database.

Log into GitHub.
Go to the umami repository.
Click Fork.
Verify you’re happy with the details - the defaults are fine, and click Create fork.

Now you’ve got a copy of the umami project in your own GitHub account. We’ll need to clone it so we have it locally, and make some adjustments.

In your terminal, clone your forked repo.

git clone [email protected]:yourGithubName/umami.git

cd to the the root directory of your forked umami project.
```
cd ~/repos/umami
```
Create a .env file.
```
touch .env
```
Edit the .env file in your preferred editor (CLI or GUI), and paste in the .env string we copied earlier. We also need to add in SKIP_DB_CHECK=1 on a new line.
```
nvim .env
```
The file should end up looking like this:
```
DATABASE_URL='mysql://fldn3vo06n:[email protected]/umami-db?sslaccept=strict'
SKIP_DB_CHECK=1
```

Ok so we’ve got a forked copy of umami, and we’ve cloned it locally. We’ve also primed it so we can connect to the database on PlanetScale.

Bootstrapping the database #

Now we need to install some utilities and bootstrap the database.

You’re going to need to install

nodejs (I use asdf to manage node)

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf install nodejs latest
asdf global nodejs latest

yarn (I use brew to manage utilities)
```
brew install yarn
```
npm-run-all (You’ll need node, which should include npm) I had to add the --legacy-peers-deps flag otherwise npm would error out with ERESOLVE unable to resolve dependency tree.
```
npm install npm-run-all --legacy-peers-deps
```

We need to be in the umami directory we ended up in during the last step, so you should be somewhere like ~/repos/umami/.

All we need to do here is build and update the database.
```
yarn run build-db && yarn run update-db
```

You can go to PlanetScale and check as you should now have tables in there. You can also click Promote to production to let PlanetScale know this database is actually important. Nice, that’s our database done.

Application #

First we gotta create a project and authorise Vercel against GitHub.

Log into Vercel.
On your Dashboard, click Create a New Project.
Click Continue with GitHub.
In the pop up, enter your GitHub username and password.
Click Sign in, and enter your second factor. If you don’t have MFA enabled, you should also do that.
Review what Vercel wants access to, and click Authorize Vercel. You may get an error, just double check the browser hasn’t prevented a pop up. If it has, allow the pop up.
In the new pop up, select the option Only select repositories and select your umami fork.
Click Install.

Now we can configure our Vercel project.

In Vercel, you should see your GitHub name and umami project listed - click Import.
On the Configure Project page, drop down the Environment Variables section.
var1: Set name to DATABASE_URL.
var1: Set value to what we copied a long time ago: mysql://fldn3vo06n:[email protected]/umami-db?sslaccept=strict
var2: Set name to SKIP_DB_CHECK.
var2: Set value to 1.
var3: Set name to HASH_SALT.
var3: Set value to a randomly generated string. Something like v5mVge03YHzoJwCj.
Then click Deploy.

Wait a few minutes, and then your umami instance should be up and available.

If you want, you can configure a custom domain inside Vercel so you can host umami under your own domain name. The Vercel documentation is a good start but TL;DR…

Go to project, Settings, Domains, enter your domain, click Add. Note the details and go wherever you manage DNS for your domain. You’ll need to add a new DNS entry of type CNAME, and point it to cname.vercel-dns.com. Once your new domain is verified and working, you can remove the originally assigned DNS name.

Configure umami #

By default, umami has a default username and password which is.. not great. So we need to change that.

Go to your umami domain (either the Vercel provided one, or your custom domain if you configured it).
Login by using the username admin and the password umami.
Click Settings at the top of the page.
Click Accounts.
On the default admin user, click Edit.
Enter a new password.
Optionally, enter a new username.
Click Save.
Click the profile icon in the top right, and click Logout.

Now we’ve change our default admin user, and we’re ready to start using umami. Adding in websites isn’t too hard, and the umami documentation is pretty solid so I won’t cover that here.

Clean-up #

Principle of least privilege #

When you’re setting everything up, you will need the database password to have the admin role, but you may only need the read/write role in day to day operations. I haven’t tested this yet, but assuming that works then it’s a sensible thing to do which more closely aligns to the principle of least privilege.

Local machine #

We don’t really need our local copy of our forked umami project. We also don’t need to keep the custom changes we made, so feel free to delete them. You will want to hold on to your DATABASE_URL string in your password manager though, as you cannot retrieve the username and password from PlanetScale.

You can also remove the command line utilities we installed, assuming you don’t need them for anything else. However if you don’t care so much, leave them hanging around for the next time you need to do some work on umami.

Free Web Analytics with umami