Setting up Ackee - privacy-aware analytics for free

If you’re any­thing like me, you have a num­ber of small open-​source projects that you’ve re­leased onto the world, and would like to see how much usage they see.
You could al­ways throw a Google An­a­lyt­ics script on them, but sell­ing out the pri­vacy of your users for the sake of an­a­lyt­ics doesn’t sit well with me - not to men­tion the issue of GDPR and cookie con­sent.

Luck­ily a num­ber of open-​source so­lu­tions have started pop­ping up for privacy-​aware an­a­lyt­ics. One of them is called Ackee. In this ar­ti­cle I’ll walk you through set­ting up Ackee using only free and man­aged host­ing so­lu­tions. This will let you get up and run­ning quickly, with­out need­ing to rent a VPS or sim­i­lar.

Get­ting Started

We’ll start by head­ing on over to the Ackee repo and have a look around. They have guides for a num­ber of dif­fer­ent host­ing providers (or host­ing on your own ma­chine using Docker), but for the sake of the ar­ti­cle we’ll be choos­ing to host on Ver­cel.
Ver­cel lets us host the back­end as a server­less func­tion, as well as the an­a­lyt­ics fron­tend, en­tirely for free.

Ver­cel doesn’t host data­bases though. For that, we’ll need to find a Mon­goDB server provider. Luck­ily Mon­goDB Atlas, the man­aged cloud so­lu­tion from Mon­goDB them­selves, has a free tier! This means we can host not only Ackee it­self, but also the data­base we use to store our con­tent, with­out hav­ing to pull our credit card out of our pock­ets.

So the plan right now is:

1. Set up a Mon­goDB data­base using the free tier of Mon­goDB Atlas. This is some­what lim­ited in how much data can be stored (up to 512MB) - but is great for get­ting started quickly, and can eas­ily be up­graded if needed.
2. Set up a Ver­cel project to host the Ackee fron­tend and GraphQL back­end. Their gen­er­ous per­sonal hobby plan al­lows us to run server­less func­tions and host sta­tic fron­tends for free, as long as we don’t ex­ceed our quota.

Host­ing the data­base

Thanks to Mon­goDB Atlas, get­ting our data­base set up takes a mat­ter of min­utes. Start by head­ing to their pric­ing page and se­lect­ing “Try for Free” on their shared plan. The first thing you should see after cre­at­ing an ac­count is the clus­ter cre­ation screen.

There aren’t any crit­i­cal set­tings to choose here; pick whichever lo­ca­tion you like the most (al­though keep­ing it close to your Ver­cel lo­ca­tion helps per­for­mance), and set a mem­o­rable clus­ter name.

When it comes to choos­ing the au­then­ti­ca­tion method you’ll want to choose a user­name you can re­mem­ber and a ran­domly gen­er­ated pass­word. It’s im­por­tant that this pass­word is se­cure, as we’ll be con­nect­ing to the data­base from Ver­cel - mean­ing we don’t know what IP we’ll be con­nect­ing from.
Keep in mind that if you choose your own pass­word (in­stead of using their “Gen­er­ate pass­word” but­ton) you’ll have to be mind­ful of spe­cial char­ac­ters.

At this point we al­most have a work­ing Mon­goDB data­base! Be­fore we can con­nect to it we still need to open up the net­work fire­wall, and find our con­nec­tion string. When prompted for the IP ad­dress that you’ll be con­nect­ing from, make sure you enter 0.0.0.0/0. Once that’s done, you should have a clus­ter ready to go on your Mon­goDB Atlas dash­board:

Click “Con­nect” and “Con­nect your ap­pli­ca­tion”, and note down the con­nec­tion string you’re shown. Don’t for­get to re­place <password> with the pass­word you cre­ated ear­lier.

And that’s it for the Mon­goDB data­base!

Host­ing Ackee

Get­ting Ackee it­self set up is equally triv­ial thanks to the easy host­ing of­fered by Ver­cel. We’ll be set­ting the project up man­u­ally, in­stead of using Ackee’s project link, be­cause doing so al­lows us to more eas­ily keep up to date in the fu­ture. Don’t worry: it’s equally as easy to set up man­u­ally, and gives you a bet­ter idea of what’s going on.

Start by fork­ing the Ackee repos­i­tory. This will cre­ate a copy of the code under your own GitHub ac­count, which is where we’ll point Ver­cel. When­ever this fork is up­dated, Ver­cel will com­pile and pub­lish the code. Since it’s a fork, stay­ing up to date is there­fore as sim­ple as click­ing the “Fetch up­stream” but­ton on the fork when­ever new ver­sions of Ackee are re­leased!

For the Ver­cel side of things, log in to Ver­cel and link up your GitHub ac­count if you haven’t al­ready. Cre­ate a new project and im­port your Ackee fork from the git repos­i­tory list.

You’ll be taken to the project con­fig­u­ra­tion page - this is where you’ll set up how Ver­cel builds the project, and which en­vi­ron­ment vari­ables are set to con­fig­ure Ackee. The most im­por­tant is the build set­tings: make sure “Build com­mand” is set to yarn build, and “Out­put di­rec­tory” is set to dist.

For the en­vi­ron­ment vari­ables you might want to refer to Ackee’s doc­u­men­ta­tion; how­ever, if you’re happy to just fol­low my con­fig­u­ra­tion, here’s what I use:

ACKEE_USER­NAME
ACKEE_PASS­WORD

These are the user­name and pass­word you want to use for log­ging in to Ackee’s an­a­lyt­ics page.

ACKEE_MON­GODB

This is the URL to your data­base. Re­mem­ber the URL we copied at the end of Host­ing the data­base? Paste that here, mak­ing sure you’ve up­dated the <pass­word> text.

ACKEE_AUTO_ORI­GIN

Should be set to true. This en­ables au­to­matic CORS head­ers: if you tell Ackee to track ex­am­ple.com, with this set­ting en­abled it will re­spond to all re­quests from ex­am­ple.com with the cor­rect CORS head­ers. If this wasn’t set to true we would have to man­u­ally spec­ify the do­mains we want in an­other env vari­able

ACKEE_TRACKER

By de­fault Ackee hosts its track­ing script on /tracker.js. I like to use the pret­tier name /ackee.js. By set­ting ACKEE_TRACKER to ackee, the script is hosted under both names.

Click “De­ploy” and **boom** you should now have a de­ployed Ackee project up and run­ning. It will take a few sec­onds for Ver­cel to build it and de­ploy it, but you should very quickly see the de­ploy­ment suc­ceed­ing and going up on the auto-​generated .vercel.app do­main. If you want, feel free to setup a cus­tom do­main - oth­er­wise, let’s con­tinue. We’re al­most done!

Con­fig­ur­ing Ackee

Head over to the do­main your Ackee is hosted on and log in using the cre­den­tials you spec­i­fied in ACKEE_USERNAME and ACKEE_PASSWORD. You’ll be greeted by an empty dash­board - let’s get some data added!

Click the “Set­tings” link in the header and scroll down to “Do­mains”. Click “New do­main” and enter the do­main as the title. You’ll want this to be of the for­mat subdomain.example.com, with­out pro­to­col or path. This way Ackee will de­tect it as a do­main, and au­to­mat­i­cally at­tach CORS head­ers (since we set ACKEE_AUTO_ORIGIN to true).

Click the newly added do­main in the do­mains list and you’ll get a popup con­tain­ing in­for­ma­tion about the do­main, in­clud­ing the embed code needed to start using Ackee. Copy the code, add it to the tar­get web­site, and voilà - you’re done!

If you’re not see­ing any data added to the dash­board when you view the tar­get site, it might be be­cause Ackee tries to avoid track­ing the owner of the site. Visit the page in an incog­nito/pri­vate browser and see if that helps. Oth­er­wise have a look at the browser con­sole. Does it com­plain about CORS head­ers? Then make sure the name of the do­main on Ackee is a valid do­main, and that it matches where the re­quests are com­ing from. As a last re­sort you can al­ways open an issue with as much in­for­ma­tion as you can about what’s going wrong.

Con­clu­sion

Con­grat­u­la­tions! You’ve just set up your very own privacy-​aware an­a­lyt­ics so­lu­tion for small per­sonal projects, for ab­solutely free.
It’s im­por­tant to re­mem­ber that the jour­ney doesn’t end here; as with any­thing in­volv­ing user data, you’ll need to eval­u­ate how this im­ple­men­ta­tion in­ter­acts with things like GDPR, the ePri­vacy Di­rec­tive and what­ever other pri­vacy reg­u­la­tion you or your users are under.
De­spite com­mon be­lief, privacy-​aware and cookie-​free an­a­lyt­ics doesn’t ex­empt you from cookie ban­ners.