Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make the release more production ready for deployment.
- Loading branch information
1 parent
9b569d8
commit 2ad8d38
Showing
5 changed files
with
172 additions
and
125 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,104 @@ | ||
buddycloud HTTP API | ||
=================== | ||
|
||
This little server implements a simple REST-like HTTP interface to a | ||
[buddycloud][bc] instance. At its heart, it is a proxy service that | ||
exposes the [XMPP][xmpp] publish-subscribe nodes underlying each buddycloud | ||
channel as Atom feeds that can be both received and modified. The | ||
interface follows the [Atom Publishing Protocol][atompub] as much | ||
as possible. | ||
|
||
[bc]: http://buddycloud.com/ | ||
[xmpp]: http://xmpp.org/ | ||
[atompub]: http://www.atomenabled.org/developers/protocol/ | ||
|
||
Setup | ||
----- | ||
|
||
The server is written on top of [Node.js](http://nodejs.org/), so you need | ||
to install that first. | ||
|
||
After getting the server's code, change to its root directory and use Node's | ||
package manager to install all other dependencies: | ||
|
||
npm install | ||
|
||
You can then start it by invoking | ||
|
||
npm start | ||
|
||
The tests are run with | ||
|
||
npm test | ||
|
||
The server needs to be configured for the buddycloud/XMPP server it should | ||
communicate with. See the *Configuration* section. | ||
|
||
Usage | ||
----- | ||
|
||
The API is described in detail at https://buddycloud.org/wiki/Buddycloud_HTTP_API. | ||
|
||
Configuration | ||
------------- | ||
|
||
You can configure the HTTP API server by copying `config.js.example` to | ||
`config.js` in the server's root directory and editing it as needed. The | ||
file is made up of multiple "profile" definitions of the form | ||
|
||
exports.profileName = { | ||
option1: value1, | ||
option2: value2, | ||
… | ||
}; | ||
|
||
Each profile specifies a different configuration. For exmaple, the `testing` | ||
profile is used by the unit tests, while `development` is thought as a | ||
configuration useful for local debugging. You can define as many other | ||
profiles as you want and load them by setting the `NODE_ENV` environment | ||
variable at startup, like so: | ||
|
||
NODE_ENV=myprofile npm start | ||
|
||
By default, the `production` profile is used. | ||
|
||
For added convenience, every option value defined in the special "underscore | ||
profile" (`_`) applies to all profiles that don't explicitly override it. | ||
As an example, the following snippet tells the server to listen on port | ||
3000 by default, but to use 3001 for the `testing` profile: | ||
|
||
exports._ = { | ||
port: 3000 | ||
}; | ||
|
||
exports.testing = { | ||
post: 3001, | ||
… | ||
} | ||
|
||
The following configuration options are supported: | ||
|
||
- **debug** (Optional): If true, the API server includes exception traces in | ||
"Internal Server Error" responses. | ||
- **port** (Required): The port on which the server listens for HTTP requests. | ||
- **xmppDomain** (Required): The XMPP domain to which the server belongs. This | ||
defines the XMPP server used for authentication and presence. | ||
- **xmppHost** (Optional): The hostname of the proxied XMPP server. This is | ||
only needed if the hostname and port cannot be resolved from the *xmppDomain* | ||
via DNS service discovery. | ||
- **xmppPort** (Optional): The proxied XMPP server's port. See above. | ||
- **xmppAnonymousDomain** (Optional): The XMPP domain used for anonymous | ||
sessions. If omitted, *xmppDomain* is assumed to handle this case. | ||
- **xmppAnonymousHost** (Optional): Like *xmppHost*, but for | ||
*xmppAnonymousDomain*. | ||
- **xmppAnonymousPort** (Optional): Like *xmppPort*, but for | ||
*xmppAnonymousDomain*. | ||
- **xmppDomain** (Required): The channel server's component domain. | ||
- **requestExpirationTime** (Optional): Number of seconds to wait for | ||
the response to an XMPP request. The default is 60. | ||
- **sessionExpirationTime** (Optional): Number of seconds before a proxied | ||
XMPP session expires. By default, this is 600 (10 minutes). | ||
- **https** (Optional): If true, the server communicates exclusively via | ||
HTTPS. *httpsCert* and *httpsKey* must be specified in this case. | ||
- **httpsCert** (Optional): The SSL certificate to use if **https** is defined. | ||
- **httpsKey** (Optional): The SSL private key to use if **https** is defined. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,104 +1,19 @@ | ||
buddycloud HTTP API | ||
=================== | ||
This is the buddycloud HTTP API server. It implements the https://buddycloud.org/wiki/Buddycloud_HTTP_API | ||
|
||
This little server implements a simple REST-like HTTP interface to a | ||
[buddycloud][bc] instance. At its heart, it is a proxy service that | ||
exposes the [XMPP][xmpp] publish-subscribe nodes underlying each buddycloud | ||
channel as Atom feeds that can be both received and modified. The | ||
interface follows the [Atom Publishing Protocol][atompub] as much | ||
as possible. | ||
# Install | ||
|
||
[bc]: http://buddycloud.com/ | ||
[xmpp]: http://xmpp.org/ | ||
[atompub]: http://www.atomenabled.org/developers/protocol/ | ||
Install documentation is at https://buddycloud.org/wiki/Install | ||
|
||
Setup | ||
----- | ||
# Issues | ||
|
||
The server is written on top of [Node.js](http://nodejs.org/), so you need | ||
to install that first. | ||
Please log any issues at https://github.com/buddycloud/buddycloud-http-api/issues | ||
|
||
After getting the server's code, change to its root directory and use Node's | ||
package manager to install all other dependencies: | ||
|
||
npm install | ||
# Developers | ||
|
||
You can then start it by invoking | ||
The project page is hosted at https://buddycloud.org/wiki/Buddycloud_HTTP_API_server. For developing please see the config file named config.js.developer-example. | ||
|
||
npm start | ||
|
||
The tests are run with | ||
# License and copyright | ||
|
||
npm test | ||
|
||
The server needs to be configured for the buddycloud/XMPP server it should | ||
communicate with. See the *Configuration* section. | ||
|
||
Usage | ||
----- | ||
|
||
The API is described in detail at https://buddycloud.org/wiki/Buddycloud_HTTP_API. | ||
|
||
Configuration | ||
------------- | ||
|
||
You can configure the HTTP API server by copying `config.js.example` to | ||
`config.js` in the server's root directory and editing it as needed. The | ||
file is made up of multiple "profile" definitions of the form | ||
|
||
exports.profileName = { | ||
option1: value1, | ||
option2: value2, | ||
… | ||
}; | ||
|
||
Each profile specifies a different configuration. For exmaple, the `testing` | ||
profile is used by the unit tests, while `development` is thought as a | ||
configuration useful for local debugging. You can define as many other | ||
profiles as you want and load them by setting the `NODE_ENV` environment | ||
variable at startup, like so: | ||
|
||
NODE_ENV=myprofile npm start | ||
|
||
By default, the `production` profile is used. | ||
|
||
For added convenience, every option value defined in the special "underscore | ||
profile" (`_`) applies to all profiles that don't explicitly override it. | ||
As an example, the following snippet tells the server to listen on port | ||
3000 by default, but to use 3001 for the `testing` profile: | ||
|
||
exports._ = { | ||
port: 3000 | ||
}; | ||
|
||
exports.testing = { | ||
post: 3001, | ||
… | ||
} | ||
|
||
The following configuration options are supported: | ||
|
||
- **debug** (Optional): If true, the API server includes exception traces in | ||
"Internal Server Error" responses. | ||
- **port** (Required): The port on which the server listens for HTTP requests. | ||
- **xmppDomain** (Required): The XMPP domain to which the server belongs. This | ||
defines the XMPP server used for authentication and presence. | ||
- **xmppHost** (Optional): The hostname of the proxied XMPP server. This is | ||
only needed if the hostname and port cannot be resolved from the *xmppDomain* | ||
via DNS service discovery. | ||
- **xmppPort** (Optional): The proxied XMPP server's port. See above. | ||
- **xmppAnonymousDomain** (Optional): The XMPP domain used for anonymous | ||
sessions. If omitted, *xmppDomain* is assumed to handle this case. | ||
- **xmppAnonymousHost** (Optional): Like *xmppHost*, but for | ||
*xmppAnonymousDomain*. | ||
- **xmppAnonymousPort** (Optional): Like *xmppPort*, but for | ||
*xmppAnonymousDomain*. | ||
- **xmppDomain** (Required): The channel server's component domain. | ||
- **requestExpirationTime** (Optional): Number of seconds to wait for | ||
the response to an XMPP request. The default is 60. | ||
- **sessionExpirationTime** (Optional): Number of seconds before a proxied | ||
XMPP session expires. By default, this is 600 (10 minutes). | ||
- **https** (Optional): If true, the server communicates exclusively via | ||
HTTPS. *httpsCert* and *httpsKey* must be specified in this case. | ||
- **httpsCert** (Optional): The SSL certificate to use if **https** is defined. | ||
- **httpsKey** (Optional): The SSL private key to use if **https** is defined. | ||
This code is Apache 2 licensed and copyright buddycloud. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
// config.js: | ||
// HTTP API server configuration. See README.md for details. | ||
|
||
// Default settings (apply to all profiles) | ||
exports._ = { | ||
port: 3000, | ||
}; | ||
|
||
// Production settings (used by default) | ||
exports.production = { | ||
xmppDomain: 'buddycloud.org', | ||
xmppAnonymousDomain: 'anon.buddycloud.org', | ||
channelDomain: 'channels.buddycloud.org', | ||
pusherComponent: 'pusher.buddycloud.org', | ||
searchComponent: 'search.buddycloud.org', | ||
homeMediaRoot: 'https://api.buddycloud.org/media' | ||
}; | ||
|
||
// Development settings (useful for local debugging) | ||
exports.development = { | ||
xmppDomain: 'localhost', | ||
xmppHost: 'localhost', | ||
channelDomain: 'localhost', | ||
pusherComponent: 'pusher.localhost', | ||
searchComponent: 'search.localhost', | ||
xmppPort: '5222', | ||
}; | ||
|
||
// Testing settings (used by the unit tests) | ||
exports.testing = { | ||
xmppDomain: 'localhost', | ||
xmppHost: 'localhost', | ||
xmppPort: '5888', | ||
sessionExpirationTime: 1 | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,35 +1,21 @@ | ||
// config.js: | ||
// HTTP API server configuration. See README.md for details. | ||
|
||
// Default settings (apply to all profiles) | ||
// buddycloud-http-api-server config file | ||
|
||
// This port should match your web server reverse proxy setting | ||
exports._ = { | ||
port: 3000, | ||
port: 9123, | ||
}; | ||
|
||
// Production settings (used by default) | ||
// Production settings | ||
exports.production = { | ||
xmppDomain: 'buddycloud.org', | ||
xmppAnonymousDomain: 'anon.buddycloud.org', | ||
channelDomain: 'channels.buddycloud.org', | ||
pusherComponent: 'pusher.buddycloud.org', | ||
searchComponent: 'search.buddycloud.org', | ||
homeMediaRoot: 'https://api.buddycloud.org/media' | ||
}; | ||
|
||
// Development settings (useful for local debugging) | ||
exports.development = { | ||
xmppDomain: 'localhost', | ||
xmppHost: 'localhost', | ||
channelDomain: 'localhost', | ||
pusherComponent: 'pusher.localhost', | ||
searchComponent: 'search.localhost', | ||
xmppPort: '5222', | ||
}; | ||
|
||
// Testing settings (used by the unit tests) | ||
exports.testing = { | ||
xmppDomain: 'localhost', | ||
xmppHost: 'localhost', | ||
xmppPort: '5888', | ||
sessionExpirationTime: 1 | ||
debug: true, | ||
xmppDomain: 'example.com', | ||
xmppAnonymousDomain: 'anon.example.com', | ||
channelDomain: 'buddycloud.example.com', | ||
pusherComponent: 'pusher.example.com', | ||
// you probably want to use the buddycloud search service | ||
searchComponent: 'search.buddycloud.com', | ||
homeMediaRoot: 'http://localhost:60080', | ||
// if using Fanout.io's API CDN, edit below | ||
fanoutRealm: 'example.com', | ||
fanoutKey: 'your-secret-key' | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
# buddycloud-http-api - buddycloud HTTP API server | ||
|
||
description "buddycloud HTTP API server" | ||
|
||
respawn | ||
exec su nobody -c "/usr/bin/node /opt/buddycloud-http-api/server.js > /var/log/buddycloud-http-api-server.log 2>&1" | ||
|