Add documentation for CLI

mxstbr · mxstbr · commit d7c10a940ec9 · 2017-01-10T13:08:47.000+01:00
diff --git a/README.md b/README.md
@@ -10,17 +10,20 @@ A tiny analytics server with less than 100 lines of code, easy to run and hack a
 
 ## Setup
 
-1. `git clone git@github.com:mxstbr/micro-analytics` to get the repo.
-2. `npm install` to install the dependencies.
-3. `npm start` to start the service.
+```
+npm install -g micro-analytics-cli
+micro-analytics
+```
+
+And that's it! 🎉 The analytics server is now running at `localhost:3000`. (see [`server-setup.md`](./server-setup.md) for instructions on acquiring a server and setting up `nginx` to make this publicly available)
 
-And that's it! 🎉 (see [`deployment.md`](./deployment.md) for deployment instructions)
+> **Note**: You can pass any option to the `micro-analytics` command that you can pass to [`micro`](https://github.com/zeit/micro). As an example, to change the host you'd do `micro-analytics -H 127.0.0.1`
 
 ## Usage
 
 ### Tracking views
 
-To track a view, simply send a request to `/<yourpath>`. If you send a `GET` request, the request will increment the views and return the total views. If you send a `POST` request, the views will increment but you don't get the total views back.
+To track a view, simply send a request to `/<id>`. If you send a `GET` request, the request will increment the views and return the total views for that id. If you send a `POST` request, the views will increment but you don't get the total views back.
 
 This is how you'd track pageviews for a website: (though note that this can be used to track anything you want)
 
@@ -34,13 +37,9 @@ This is how you'd track pageviews for a website: (though note that this can be u
 </script>
 ```
 
-If you just want to get the views for a path and don't want to increment the views during a `GET` request, set `inc` to `false` in your query parameter. (`/<yourpath>?inc=false`)
-
-If you want to get all views for all paths, set the `all` query parameter to `true`. (`/?all=true`)
-
-## Contributing
+If you just want to get the views for an id and don't want to increment the views during a `GET` request, set `inc` to `false` in your query parameter. (`/<id>?inc=false`)
 
-If you run `npm run dev` the server will restart every time you edit the code. Perfect for development of `micro-analytics`!
+If you want to get all views for all ids, set the `all` query parameter to `true`. (`/?all=true`)
 
 ## Built with
 
diff --git a/contributing.md b/contributing.md
@@ -0,0 +1,7 @@
+# Contributing
+
+## Local setup
+
+1. Clone the repository with `git clone git@github.com:mxstbr/micro-analytics.git`
+2. Install the dependencies with `npm install` (or `yarn install` if you have `yarn`)
+3. Run the server in dev mode with `npm run dev`, which will restart the server everytime you edit the code.
diff --git a/server-setup.md b/server-setup.md
@@ -1,26 +1,35 @@
-# Deployment
+# Server Setup
 
-Deploying this service is a short three step process. This assumes you already have a server with an OS of your choice that runs Node setup, if not refer to the [acquire a server](#acquire-a-server) section.
+Running `micro-analytics` on a server is a simple two step process:
 
-1. Upload the files of the service to your server (you should be able to do this on your own)
-2. Start and daemonize the app with `pm2`
-3. Setup `nginx` as a reverse proxy to make your service publicy accessible
+1. Start and daemonize the app with `pm2`
+2. Setup `nginx` as a reverse proxy to make your service publicy accessible
+
+## Prerequisite: A server
+
+If you don't have a server to run this on yet, here is what I do:
+
+I use and like [DigitalOcean](https://m.do.co/c/d371ed7f99af) (referral link) for my servers. A simple, 5$/month droplet will suffice to run this service reliably. (upgrading to more power in case of big traffic is two clicks away too)
+
+Make sure to choose the `NodeJS x.x.x on 16.04` (where `x.x.x` is the highest version number you can find) one-click app when creating the droplet to get the server fully setup with Node and Ubuntu.
 
 ## Start and deamonize the app
 
-Once all the files for this microservice are uploaded we'll use `pm2` to start and deamonize the app. This means that the app isn't bound to the terminal, and we'll also make `pm2` start the app when the server start.
+Install `micro-analytics` on your server by running `npm install -g micro-analytics-cli` in its shell.
+
+We'll use `pm2` to start and deamonize the app. This means that the app isn't bound to the terminal, and we'll also make `pm2` start the app when the server start. (this avoids the service being down in case your server reboots)
 
-First run `npm install -g pm2` to get `pm2`, then run `pm2 start npm -- start`. This tells `pm2` to run `npm start` in the background.
+First run `npm install -g pm2` to get `pm2`, then run `pm2 start micro-analytics`. This tells `pm2` to run `micro-analytics` in the background.
 
 To make sure our service stays up even if the server reboots we run `pm2 startup ubuntu` (replace `ubuntu` with whatever OS you're using) and `pm2 save`.
 
 ## Set up `nginx`
 
-Get `nginx` by running `sudo apt-get install nginx`, then configure it to reroute all incoming requests to the server to our server.
+Get `nginx` by running `sudo apt-get install nginx`, then configure it to reroute all incoming requests to the server to `micro-analytics`.
 
 Delete the default site from nginx by running `sudo rm /etc/nginx/sites-enabled/default`, then create a new one by running `sudo touch /etc/nginx/sites-enabled/<yoursite>`. (replace `<yoursite>` with your site name)
 
-We want to reroute all requests for any path that come in to our service, so edit the `/etc/nginx/sites-enabled/<yoursite>` file to look like this:
+We want to reroute all requests for any path that come in to `localhost:3000` (where `micro-analytics` is running), so edit the `/etc/nginx/sites-enabled/<yoursite>` file to look like this:
 
 ```nginx
 server {
@@ -37,11 +46,3 @@ server {
 ```
 
 (note that I have no idea what I'm doing here, this was copied from [this tutorial](https://www.digitalocean.com/community/tutorials/how-to-configure-nginx-as-a-reverse-proxy-for-apache))
-
-## Acquire a server
-
-If you don't have a server to deploy this on just yet, here is what I do:
-
-I use and like [DigitalOcean](https://m.do.co/c/d371ed7f99af) (referral link) for my servers. A simple, 5$/month droplet will suffice to run this service reliably. (upgrading to more power in case of big traffic is two clicks away too)
-
-Make sure to choose the `NodeJS x.x.x on 16.04` (where `x.x.x` is the highest version number you can find) one-click app when creating the droplet to get the server fully setup with Node and Ubuntu.
