Add documentation

msholly · Feb 10, 2016 · 39919c1 · 39919c1
1 parent a17bcdf
commit 39919c1
Show file tree

Hide file tree

Showing 9 changed files with 172 additions and 146 deletions.
diff --git a/README.md b/README.md
@@ -32,36 +32,7 @@ It uses GitHub as a backend to store assets, and it can easily be deployed to He
 
 #### Deploy it / Start it
 
-Install dependencies using:
-
-```
-$ npm install
-```
-
-This service requires to be configured using environment variables:
-
-```
-# Set the port for the service
-$ export PORT=6000
-
-# Access token for the GitHub API (requires permissions to access the repository)
-# If the repository is public you do not need to provide an access token
-# you can also use GITHUB_USERNAME and GITHUB_PASSWORD
-$ export GITHUB_TOKEN=...
-
-# ID for the GitHub repository
-$ export GITHUB_REPO=Username/MyApp
-
-# Authentication for the private API
-$ export API_USERNAME=hello
-$ export API_PASSWORD=world
-```
-
-Then start the application using:
-
-```
-$ npm start
-```
+[Follow our guide to deploy Nuts](docs/dpeloy.md).
 
 #### Assets for releases
 
@@ -96,121 +67,8 @@ Nuts provides urls to access releases assets. These assets are cached on the dis
 
 Platforms can be detected from user-agent and are normalized to values: `osx`, `osx_32`, `osx_64`, `linux`, `linux_32`, `linux_64`, `windows`, `windows_32`, `windows_64`.
 
-Non-prefixed platform will be resolve to 32 bits (except for OSX).
+Non-prefixed platform will be resolve to 32 bits (except for OS X).
 
 #### Auto-updater / Squirrel
 
-This server provides an endpoint for [Squirrel auto-updater](https://github.com/atom/electron/blob/master/docs/api/auto-updater.md): `http://download.myapp.com/update/osx/:currentVersion`.
-
-###### Squirrel.Mac
-
-This url requires different parameters to return a correct version: `version` and `platform`.
-
-For example with Electron's `auto-updater` module:
-
-```js
-var app = require('app');
-var os = require('os');
-var autoUpdater = require('auto-updater');
-
-var platform = os.platform() + '_' + os.arch();
-var version = app.getVersion();
-
-autoUpdater.setFeedUrl('http://download.myapp.com/update/'+platform+'/'+version);
-```
-
-###### Squirrel.Windows
-
-Nuts will serve NuGet packages on `http://download.myapp.com/update/win32/:version/RELEASES`.
-
-Your application just need to configurer `Update.exe` or `Squirrel.Windows` to use `http://download.myapp.com/update/win32/:version` as a feed url (:warning: without query parameters).
-
-You'll just need to upload as release assets: `RELEASES`, `*-delta.nupkg` and `-full.nupkg` (files generated by `Squirrel.Windows` releaser).
-
-#### ChangeLog
-
-Nuts provides a `/notes` endpoint that output release notes as text or json.
-
-#### Private API
-
-A private API is available to access more infos about releases and stats. This API can be protected by HTTP basic auth (username/password) using configuration `API_USERNAME` and `API_PASSWORD`.
-
-List versions:
-
-```
-GET http://download.myapp.com/api/versions
-```
-
-Get details about specific version:
-
-```
-GET http://download.myapp.com/api/version/1.1.0
-```
-
-Resolve a version:
-
-```
-GET http://download.myapp.com/api/resolve?platform=osx&channel=alpha
-```
-
-List channels:
-
-```
-GET http://download.myapp.com/api/channels
-```
-
-Get stats about downloads:
-
-```
-GET http://download.myapp.com/api/stats
-```
-
-#### GitHub Webhook
-
-Add `http://download.myapp.com/refresh` as a GitHub webhook to refresh versions cache everytime you update a release on GitHub.
-
-The secret can be configured using `GITHUB_SECRET` (default value is `secret`).
-
-#### Integrate it as a middleware
-
-Nuts can be integrated into a Node.JS application as a middleware. Using the middleware, you can add custom authentication on downloads or analytics for downloads counts.
-
-```js
-var express = require('express');
-var Nuts = require('nuts-serve');
-
-var app = express();
-var nuts = Nuts(
-    // GitHub configuration
-    repository: "Me/MyRepo",
-    token: "my_api_token",
-
-    // Timeout for releases cache (seconds)
-    timeout: 60*60,
-
-    // Folder to cache assets (by default: a temporary folder)
-    cache: './assets',
-
-    // Cache configuration
-    cacheMax: 500 * 1024 * 1024,
-    cacheMaxAge: 60 * 60 * 1000,
-
-    // Pre-fetch list of releases at startup
-    preFetch: true,
-
-    // Secret for refresh webhook
-    refreshSecret: 'my-secret',
-
-    // Middlewares
-    onDownload: function(version, req, res, next) {
-        console.log('download', download.version.tag, "on channel", download.version.channel, "for", download.platform.type);
-        next();
-    },
-    onAPIAccess: function(req, res, next) {
-        next();
-    }
-);
-
-app.use('/myapp', nuts);
-app.listen(4000);
-```
+This server provides an endpoint for [Squirrel auto-updater](https://github.com/atom/electron/blob/master/docs/api/auto-updater.md), it supports both [OS X](docs/update-osx.md) and [Windows](docs/update-windows.md).
diff --git a/docs/README.md b/docs/README.md
@@ -5,3 +5,12 @@ Please make sure that you use the documents that match your Nuts version.
 ### FAQ
 
 There are questions that are asked quite often, [check this out before creating an issue](faq.md).
+
+### Guides
+
+- [Deploy it!](deploy.md)
+- [Setup GitHub webhook](github.md)
+- [OS X auto updater](update-osx.md)
+- [Windows auto updater](update-windows.md)
+- [Debug API](api.md)
+- [Use it as a node module](module.md)
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,27 @@
+# API
+
+A debug API is available to access more infos about releases. This API can be protected by HTTP basic auth (username/password) using configuration `API_USERNAME` and `API_PASSWORD`.
+
+#### List versions:
+
+```
+GET http://download.myapp.com/api/versions
+```
+
+#### Get details about specific version:
+
+```
+GET http://download.myapp.com/api/version/1.1.0
+```
+
+#### Resolve a version:
+
+```
+GET http://download.myapp.com/api/resolve?platform=osx&channel=alpha
+```
+
+#### List channels:
+
+```
+GET http://download.myapp.com/api/channels
+```
diff --git a/docs/deploy.md b/docs/deploy.md
@@ -0,0 +1,40 @@
+# Deployment
+
+Nuts can be easily be deployed to a state-less server or PaaS.
+
+### On Heroku:
+
+[![Deploy](https://www.herokucdn.com/deploy/button.png)](https://heroku.com/deploy)
+
+### On your own server:
+
+Install dependencies using:
+
+```
+$ npm install
+```
+
+This service requires to be configured using environment variables:
+
+```
+# Set the port for the service
+$ export PORT=6000
+
+# Access token for the GitHub API (requires permissions to access the repository)
+# If the repository is public you do not need to provide an access token
+# you can also use GITHUB_USERNAME and GITHUB_PASSWORD
+$ export GITHUB_TOKEN=...
+
+# ID for the GitHub repository
+$ export GITHUB_REPO=Username/MyApp
+
+# Authentication for the private API
+$ export API_USERNAME=hello
+$ export API_PASSWORD=world
+```
+
+Then start the application using:
+
+```
+$ npm start
+```
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,10 +1,21 @@
 # Nuts FAQ
 
-### Can I use a private repository ?
+### Can I use a private repository?
 
 Nuts is designed to proxy assets from a private repository to the public.
 
 ### Can I use a GitHub Enterprise / GitLab repository?
 
 Since version 3.0.0, Nuts can works with [other backends](https://github.com/GitbookIO/nuts/tree/master/lib/backends) than GitHub. Feel free to post a Pull-Request to implement such backends!
 
+### Can I deploy it to Heroku?
+
+[Yes you can](deploy.md)!
+
+### What file should I upload to the GitHub release?
+
+Nuts can detect the type of file from its filename, there is no strict policy on file naming. Nuts tries to respect the filename/extension conventions for the different platforms. request:)
+
+- Windows: `.exe`, etc
+- Linux: `.deb`, `.tar.gz`, etc
+- OS X: `.dmg`, etc
diff --git a/docs/github.md b/docs/github.md
@@ -0,0 +1,5 @@
+# GitHub Setup
+
+Add `http://download.myapp.com/refresh` as a GitHub webhook to refresh versions cache everytime you update a release on GitHub.
+
+The secret can be configured using `GITHUB_SECRET` (default value is `secret`).
diff --git a/docs/module.md b/docs/module.md
@@ -0,0 +1,41 @@
+# Use Nuts as a node module
+
+Nuts can be integrated into a Node.JS application as a node module. Using the middleware, you can add custom authentication on downloads or analytics for downloads counts.
+
+#### Installation
+
+Nuts can be installed as a local dependency using `npm`:
+
+```
+$ npm install nuts-serve
+```
+
+#### Usage
+
+```js
+var express = require('express');
+var Nuts = require('nuts-serve').Nuts;
+
+var app = express();
+
+var nuts = Nuts({
+    // GitHub configuration
+    repository: "Me/MyRepo",
+    token: "my_api_token"
+});
+
+app.use('/myapp', nuts.router);
+app.listen(4000);
+```
+
+### Configuration
+
+- `cache`: (string) Path to the cache folder, default value is a temprary folder
+- `cacheMax`: (int) Max size of the cache (default is 500MB)
+- `cacheMaxAge`: (int) Maximum age in ms (default is 1 hour)
+- `preFetch`: (boolean) Pre-fetch list of releases at startup (default is true)
+
+GitHub specific configuration:
+
+- `refreshSecret`: (string) Secret for the GitHub webhook
+
diff --git a/docs/update-osx.md b/docs/update-osx.md
@@ -0,0 +1,24 @@
+# Auto-updater on OS X
+
+Nuts provides a backend for the [Squirrel.Mac](https://github.com/Squirrel/Squirrel.Mac) auto-updater. Squirrel.Mac is integrated by default in [Electron applications](https://github.com/atom/electron).
+
+### Endpoint
+
+The endpoint for **Squirrel.Mac** is `http://download.myapp.com/update/osx/:currentVersion`.
+
+This url requires different parameters to return a correct version: `version` and `platform`.
+
+### Electron Example
+
+For example with Electron's `auto-updater` module:
+
+```js
+var app = require('app');
+var os = require('os');
+var autoUpdater = require('auto-updater');
+
+var platform = os.platform() + '_' + os.arch();
+var version = app.getVersion();
+
+autoUpdater.setFeedUrl('http://download.myapp.com/update/'+platform+'/'+version);
+```
diff --git a/docs/update-windows.md b/docs/update-windows.md
@@ -0,0 +1,11 @@
+# Auto-updater on Windows
+
+Nuts provides a backend for the [Squirrel.Windows](https://github.com/Squirrel/Squirrel.Windows) auto-updater.
+
+Refer to the [Squirrel.Windows documentation](https://github.com/Squirrel/Squirrel.Windows/tree/master/docs) on how to setup your application.
+
+Nuts will serve NuGet packages on `http://download.myapp.com/update/win32/:version/RELEASES`.
+
+Your application just need to configure `Update.exe` or `Squirrel.Windows` to use `http://download.myapp.com/update/win32/:version` as a feed url (:warning: without query parameters).
+
+You'll just need to upload as release assets: `RELEASES`, `*-delta.nupkg` and `-full.nupkg` (files generated by `Squirrel.Windows` releaser).