From 39919c18f4df1348ad0f81a04844e4f012472ef7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Samy=20Pess=C3=A9?= Date: Wed, 10 Feb 2016 23:02:03 +0100 Subject: [PATCH] Add documentation --- README.md | 148 +---------------------------------------- docs/README.md | 9 +++ docs/api.md | 27 ++++++++ docs/deploy.md | 40 +++++++++++ docs/faq.md | 13 +++- docs/github.md | 5 ++ docs/module.md | 41 ++++++++++++ docs/update-osx.md | 24 +++++++ docs/update-windows.md | 11 +++ 9 files changed, 172 insertions(+), 146 deletions(-) create mode 100644 docs/api.md create mode 100644 docs/deploy.md create mode 100644 docs/github.md create mode 100644 docs/module.md create mode 100644 docs/update-osx.md create mode 100644 docs/update-windows.md diff --git a/README.md b/README.md index a0510597..d236cf54 100644 --- 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 index e509c933..d52a96ab 100644 --- 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 new file mode 100644 index 00000000..4c9f88c4 --- /dev/null +++ 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 new file mode 100644 index 00000000..0367f0f7 --- /dev/null +++ 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 index 85828c77..b5441010 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,6 @@ # 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. @@ -8,3 +8,14 @@ Nuts is designed to proxy assets from a private repository to the public. 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 new file mode 100644 index 00000000..b5938bde --- /dev/null +++ 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 new file mode 100644 index 00000000..f8fd3657 --- /dev/null +++ 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 new file mode 100644 index 00000000..f33ae9ed --- /dev/null +++ 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 new file mode 100644 index 00000000..61d540e8 --- /dev/null +++ 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).