search

electerious / Ackee

Self-hosted, Node.js based analytics tool for those who care about privacy.
https://ackee.electerious.com
MIT License
4.2k stars 351 forks source link

Better docs for Vercel #279

Open pixelass opened 2 years ago

pixelass commented 2 years ago

Expected

  1. As a user I expect to be able to follow the guide so I can understand how to set up Ackee.
  2. As a user I expect to be able to click the Vercel Button in order to deploy Ackee automatically

Actual:

  1. The docs don't explain what needs to be done to setup MongoDB
  2. The Vercel Button clones the repo instead of forking it

It is unclear to me how to setup Ackee on Vercel.

I tried two options:

  1. Vercel Button

This actually clones the repo instead of forking it.

  1. Fork manually and deploy

This seems to be the better option since it allows to "Fetch upstream"

Actual Problem with Docs:

What is mostly unclear and undocumented is: "Setting up MongoDB"

The docs mention:

Set environment variables ACKEE_USERNAME, ACKEE_PASSWORD, ACKEE_MONGODB, and ACKEE_ALLOW_ORIGIN.

  1. What should I put in ACKEE_MONGODB
  2. What should I put in ACKEE_ALLOW_ORIGIN

Sorry if these questions seem dumb but I have no experience with MongoDB or Ackee.

It would be amazing if you could give me a hint on what needs to be done here.

I assume that ACKEE_ALLOW_ORIGIN would be the domain of the deployment but I'm unsure about it. I have no idea what ACKEE_MONGODB does as it does not seem to be documented anywhere. Do I need to setup a mongoDB instance myself or should this work out of the box?

electerious commented 2 years ago

Thanks for the feedback! We should definitely improve this part in the documentation. It also seems that the Vercel deploy website changed a bit and I can see why the documented steps aren't proving enough information.

This could help for now:

To set the ACKEE_MONGODB environment variable you need a MongoDB instance running somewhere. There're multiple services you can use, but I guess that MongoDB Atlas is the best one to start with: https://www.mongodb.com/de-de/cloud/atlas

Whatever service you choose, you will get a MongoDB connection URI. That's the string you should use for ACKEE_MONGODB: https://github.com/electerious/Ackee/blob/master/docs/Options.md#database

The ACKEE_ALLOW_ORIGIN is explained here: https://github.com/electerious/Ackee/blob/master/docs/CORS%20headers.md#platforms-as-a-service-configuration

I assume that ACKEE_ALLOW_ORIGIN would be the domain of the deployment but I'm unsure about it.

It should be the website(s) you want to track. Otherwise they can't send data to your Ackee instance. It's basically a list of domains you allow to make request to your Ackee instance.

Let me know if you have other questions. A PR for an improved documentation is also welcome!

pixelass commented 2 years ago

Thx for the fast reply. I'll open a PR with the interesting parts of your comment, as soon as I manage to get this running. (Might take a few days/weeks since we're on a tight schedule)