Docs Kegbot Org Kegbot Server en Stable
Docs Kegbot Org Kegbot Server en Stable
Docs Kegbot Org Kegbot Server en Stable
Bevbot LLC
2 Install Guide 5
2.1 Install dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Set up an environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Install Kegbot Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Create the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Run Redis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Run the Setup Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.7 Configure E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
i
7.2 Date errors while viewing sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.3 Statistics are not regenerated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.4 Tweets (or other plugin events) are not sent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
9 Changelog 25
9.1 Version 1.2.3 (2015-01-12) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
9.2 Version 1.2.2 (2015-01-03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
9.3 Version 1.2.1 (2014-12-02) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
9.4 Version 1.2.0 (2014-12-01) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
9.5 Version 1.1.1 (2014-11-11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.6 Version 1.1.0 (2014-09-19) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.7 Version 1.0.2 (2014-08-21) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.8 Version 1.0.1 (2014-07-21) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
9.9 Version 1.0.0 (2014-06-24) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
ii
Kegbot Documentation
Kegbot Server is the brains of a Kegbot system. This guide will help you install, configure, and run a new Kegbot
server.
Contents:
Contents 1
Kegbot Documentation
2 Contents
CHAPTER 1
Kegbot Server is the web service behind Kegbot. It serves as both a frontend for visual navigaton of drinking activity,
as well as the backend for all Kegbot data.
New: The easiest way to get going is by following the Digital Ocean Install Instructions.
For those already familiar with Linux, these ultra-quick install instructions may suffice:
1.2 Dependencies
Kegbot Server is built on a number of open source projects. The major dependencies are:
• Python 2.7
• MySQL or PostgreSQL
• Redis 2.8 or newer
In addition, Kegbot Server requires several Python modules which are installed automatically by the Python package
manager.
3
Kegbot Documentation
Kegbot Server should run on any UNIX-based operating system. Since there are many possible distributions, the
examples in this document are written for Debian/Ubuntu and Mac OS X (Homebrew) package managers.
1.4 License
Kegbot Server is licensed under the GNU General Public License v2.0. You must accept this license before installing
or using Kegbot Server.
Install Guide
Before we begin, be sure Kegbot’s major dependencies are available on your your system.
On Ubuntu or Debian, use apt-get:
$ sudo apt-get install \
python-dev \
python-pip \
libjpeg-dev \
libmysqlclient-dev \
redis-server \
mysql-client \
mysql-server \
redis-server \
supervisor \
nginx
The first thing you’ll need is the Python virtualenv package. You probably already have this, but if not, you can install
it with:
5
Kegbot Documentation
Once that’s done, chose a directory for the Kegbot Server environment and create it with virtualenv. In our examples
we’ll use /data/kb:
$ virtualenv /data/kb
$ source /data/kb/bin/activate
(kb) $
Tip: You must activate your virtualenv before updating Kegbot, as well as before running any command-line Kegbot
programs.
Once you have the environment set up, you’re ready to install Kegbot Server:
Sit back and relax; this command will download and install the latest release, along with all of its Python dependencies.
Create a new database to store your Kegbot data. On MySQL, the command to use is:
We also recommend creating a new MySQL user solely for Kegbot access. Run the following command, replacing
“pw” with a password of your choice:
If you installed Redis, it’s probably already running. Verify by pinging it:
$ redis-cli ping PONG
Warning: Kegbot uses Redis databases 0 and 1 by default. If you are using the same Redis server for other
programs, we recommend using separate databases.
(kb) $ setup-kegbot.py
When finished, you should have a settings file in ~/.kegbot/local_settings.py that you can examine.
After running the wizard, two important settings should have been configured: the media and static files directories.
MEDIA_ROOT This variable controls where Kegbot stores uploaded media: pictures added during account registra-
tion or pours, for example.
STATIC_ROOT This variable controls where Kegbot’s static media is stored, such as built-in style sheets and images
shown on the web page.
Warning: Never place other content in STATIC_ROOT, and always be sure it is set to a directory that Kegbot
can completely overwrite. For more information, see Django’s documentation for managing static files.
By now you have Kegbot installed; it’s now time to run the server!
Kegbot Server includes a simple built-in web server (part of Django). This is not a high performance web server, but
works well during testing.
Launch the web server with the following command:
0 errors found
Django version 1.6.2, using settings 'pykeg.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
The admin account you just created has access to an additional tab in the navigation bar: “Admin”.
Head over to “Taps”. Taps define what beer is currently available in the system. By default, two taps are created, but
you can add more if you need them. If you’re only using one tap, don’t worry about the second one.
9
Kegbot Documentation
Before you can pour a drink, you should add a new Keg to the tap.
By default, the built-in web server only accepts connections from the local machine. To allow external computers to
reach this server, specify the bind address when running it:
Certain features, such as stats computation, Twitter checkins and web hook support, require a non-webserver process
in order to run in the background Kegbot uses Celery as its task queue.
Celery is automatically installed with kegbot. You can try running it in the foreground:
Be sure Celery is always running when your server is running. If it isn’t, some features will not work. See Production
Setup with Gunicorn, Nginx, and Supervisor for instructions on automatically launching Celery in the background.
Congratulations! Your Kegbot Server should be basically functional: ready to accept new user registrations and drink
reports. In the next chapters, we’ll go over tweaking your setup for a long-running production environment.
Note: It is possible to use other components in place of the ones recommended here; you’ll need to figure out those
steps yourself.
4.1 Gunicorn
Starting with version 0.9.4, Gunicorn is automatically installed with Kegbot Server. You can test it with the built-in
command, run_gunicorn:
4.2 Nginx
Nginx is a fast and flexible HTTP server written in C. You can install it with the nginx package on Ubuntu:
11
Kegbot Documentation
After nginx is installed and started, a default HTTP server will be running on port 80.
Kegbot includes a sample nginx configuration file in the deploy/ directory which needs to be tailored to your setup.
The contents are also included below:
upstream kegbot {
server 127.0.0.1:8000;
}
server {
listen 80;
tcp_nopush on;
tcp_nodelay on;
gzip on;
gzip_disable "msie6";
gzip_types text/plain text/css application/x-javascript text/xml application/xml
˓→application/xml+rss text/javascript;
gzip_vary on;
keepalive_timeout 0;
client_max_body_size 10m;
location / {
proxy_redirect off;
proxy_set_header Host $host:$server_port;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Protocol $scheme;
proxy_pass http://kegbot;
}
location /media/ {
alias /data/kegbot/www/media/;
access_log off;
log_not_found off;
expires 7d;
add_header pragma public;
add_header cache-control "public";
}
(continues on next page)
location /static/ {
alias /data/kegbot/www/static/;
access_log off;
log_not_found off;
expires 7d;
add_header pragma public;
add_header cache-control "public";
}
location /robots.txt {
root /data/kegbot/www/static/;
access_log off;
log_not_found off;
}
location /favicon.ico {
root /data/kegbot/www/static/;
access_log off;
log_not_found off;
}
Create a copy of this file, editing the paths noted in the comments at the top. Finally, install it:
$ sudo cp kegbot-nginx.conf /etc/nginx/sites-available/
$ sudo rm /etc/nginx/sites-enabled/default
$ sudo ln -s /etc/nginx/sites-available/kegbot-nginx.conf /etc/nginx/sites-enabled/
$ sudo service nginx restart
4.3 supervisord
Supervisor manages programs according to its configuration files. Once again, there is a template in the deploy/
directory:
# Supervisor configuration for Kegbot server.
#
# Instructions:
# - Replace "/data/kegbot/kb/bin" with the installed path of the kegbot
# programs.
# - Replace "user=ubuntu" with the username you wish to run the programs.
# - Edit paths.
# - Copy to /etc/supervisor/conf.d/kegbot.conf
[group:kegbot]
programs=gunicorn,workers
[program:gunicorn]
(continues on next page)
4.3. supervisord 13
Kegbot Documentation
[program:workers]
command=/data/kegbot/kb/bin/kegbot run_workers
directory=/data/kegbot
stopasgroup=true
user=ubuntu
autostart=true
autorestart=true
redirect_stderr=true
Make a copy of this file, editing the fields as noted, and install it:
By now you’ve got a default Kegbot server running. There are several more features you can enable by installing and
configuring optional components.
5.1 Plugins
Kegbot Server ships with a few built-in plugins. Most plugins require configuration before they can be used. To
configure, see the Extras section of the admin tab.
5.1.1 Twitter
5.1.2 Foursquare
The Foursquare plugins allows your users to automatically check-in to your own Foursquare venue the first time they
pour in a session.
To configure, get a Foursquare developer account and input the Client ID, Client Secret, and Venue ID through the
Kegbot admin configuration page for Foursquare.
15
Kegbot Documentation
Users will also need to link their own Foursquare accounts (under the Accounts tab) before the system will check in
on their behalf.
5.1.3 Untappd
The Untappd plugin is similar to the Foursquare plugin: when the system is configured and a drinker with a linked
account pours, the plugin will check the user in to that beer type.
The beer type must have an Untappd ID saved in your Kegbot beer database; otherwise, Kegbot does not know which
Untappd beer to log.
To configure, get Untappd developer access and configure Kegbot with the credentials. Users will need to link their
own Untappd accounts (under the Account tab) before the system can check them in.
You may wish to write your own service to respond to Kegbot events. The Web Hooks plugin is an excellent way to
integrate with Kegbot, without being tightly coupled to the server itself.
When activated, the Kegbot server will issue an HTTP POST to every configured URL whenever a system event
occurs. The body of the post data contains a single JSON message, which includes the following fields:
• type: The type of the message. Currently, this is always 'event'.
• data: The payload of the message. This will be the system event object.
The system event JSON structure will be identical to those events seen at the /api/events/ endpoint.
Certain add-ons provide enhanced developer/debugging functionality. You probably won’t be interested in these unless
you’re working on Kegbot Server code.
Your Kegbot server can log internal errors and exceptions to a Sentry web server. This is mostly useful for monitoring
a production site. You can read the Sentry docs to run your own server, or you can pay for a hosted Sentry server.
Configuring Kegbot to log to your Sentry server is easy:
1. Be sure you have Raven, the sentry client, installed:
2. In your local_settings.py, add your Sentry URL (shown in your Sentry dashboard):
RAVEN_CONFIG = {
'dsn': 'http://foo:bar@localhost:9000/2',
}
Developers can get extra information while Kegbot is running by installing Django Debug Toolbar.
To install:
When this package is installed and settings.DEBUG is True, Kegbot will automatically enable it; you don’t need
to do any additional configuration.
Kegbot can post server-related counters and other statistics to StatsD. This is primarily of interest to developers. To
install:
Once installed, you may optionally change the default settings by adding entries to local_settings.py:
• STATSD_CLIENT (default is statsd.client)
• STATSD_HOST (default is localhost)
• STATSD_PORT (default is 8125)
• STATSD_PREFIX (default is empty)
If you have the debug toolbar installed, you may instead route StatsD pings to it by setting
KEGBOT_STATSD_TO_TOOLBAR = True.
Consult the django-statsd configuration docs for more details.
Occasionally we make changes to Kegbot that require special steps or attention when upgrading. Though the section
below covers the most commonly-needed upgrade steps, always read the upgrade notes in the changelog first.
19
Kegbot Documentation
The built-in web servers (kegbot runserver and kegbot run_gunicorn) do not serve static files – any
URLs beginning with /media and /static – when DEBUG = False.
This behavior is intentional: serving static files this way is “grossly inefficient” and “probably insecure” according to
the Django developers. As a result, Kegbot will only do it when DEBUG = True.
To fix, follow the production setup guide, which configures these files to be served directly by the fronting web server
Nginx. Alternatively, accept the consequences of running a non-production config and set DEBUG = True.
This issue arsies when MySQL does not have complete time zone information, and is discussed in Django ticket 21629
and in the MySQL documentation.
For most systems, the following command will fix the issue:
Statistics are recomputed in a background task. In order for this to work, the task queue (Celery) must be running.
You can check queue status through the Worker Status section in the admin console.
21
Kegbot Documentation
Plugins that report to external services, such as the Twitter plugin, require the task queue to be running. See Statistics
are not regenerated.
On Twitter specifically, identical tweets – those with the exact same message content – may be supressed by Twitter.
You can work around this by ensuring the message is unique, for example by always including the drink URL.
This section lists settings that may be added to local_settings.py. Most of these options serve uncommon
needs.
In addition to settings described here, any of Django’s built-in settings may be listed in local_settings.py.
ALLOWED_HOSTS
Lists allowed hostnames that the server will respond to. See the Django documentation for ALLOWED_HOSTS
for more information.
Default is ['*'] (any hostname accepted).
ALLOWED_HOSTS = ['kegbot.example.com']
KEGBOT_BASE_URL
Ordinarily, Kegbot will infer your site’s hostname and base URL from incoming requests. This hostname is
used to compose full URLs, for example when generating the links in outgoing e-mails and plugin posts.
In some situations you may want to set this value explicitly, for example if your server is available on multiple
hostnames.
Default is unset (automatic mode).
KEGBOT_BASE_URL = 'http://mykegbot.example:8001/'
KEGBOT_ENABLE_ADMIN
When set to true, the Django Admin Site will be enabled, allowing you to browse and edit raw Kegbot data
through a web interface.
Warning: Editing raw Kegbot data through the admin interface may leave your system in a corrupt or inconsis-
tent state.
Default is False.
KEGBOT_ENABLE_ADMIN = True
23
Kegbot Documentation
LOGGING['handlers']['redis']['url']
When specified, this setting gives the URL of a redis instance to use for temporary log data. The URL is parsed
by redis.from_url.
Default is redis://localhost:6379.
Changelog
Upgrade Procedure: Please follow Upgrade from a Previous Version for general upgrade steps.
• Keg management improvements: The new “Keg Room” view shows kegs by status, and allows kegs to be
manually moved between “available” and “finished” states.
• Fancy keg graphics.
25
Kegbot Documentation
• Backup file format has changed. Downgrade to v1.1 to restore from an earlier file format.
• Django 1.7 update.
• Flow sensing and multiuser features can be hidden.
• Statistics now properly consider local timezone (#199).
• Some new keg sizes are supported (#318).
• Keg full volume and beverage type can be edited (#279).
• Fullscreen mode.
• New keg artwork.
• New internal beverage fields: IBU, SRM, star rating, and color.
26 Chapter 9. Changelog