Setup

There are two different ways to setup Barcode Buddy: Either a bare metal approach or docker

Docker

Requirements

  • A host running docker

Installation

To download, run the following command, and replace YOURTAG with one from the list below:

docker pull f0rc3/barcodebuddy-docker:YOURTAG
Tag Architecture Version
latest x86-64 stable
arm32v7-latest armhf stable
arm64v8-latest arm64 stable
latest-dev x86-64 unstable
arm32v7-latest-dev armhf unstable
arm64v8-latest-dev arm64 unstable

Most of the time, you will need the latest tag. If you are running docker on a Raspberry Pi, you will need the arm32v7-latest tag.

Stable indicates, that you are using the latest release which should work without any bugs. Unstable is the latest developer version, which might include more features, but could also contain bugs.

If you don’t want to download the prebuilt image, you can find the Dockerfile on the Github project page .

Starting the Container

To start the container, run the following command:

docker run -d -v bbconfig:/config -p 80:80 -p 443:443 f0rc3/barcodebuddy-docker:YOURTAG

You can now open http://DOCKER_HOST_IP/ to set up BarcodeBuddy. If you are already serving a webserver on your Docker host, you need to change the ports, eg.:

docker run -d -v bbconfig:/config -p 8080:80 -p 9443:443 f0rc3/barcodebuddy-docker:latest

The following arguments can also be passed:

Argument Value Effect
ATTACH_BARCODESCANNER true/false Use attached barcode scanner
IGNORE_SSL_CA true/false Accept self-signed SSL certificates
IGNORE_SSL_HOST true/false Accept SSL certificates where the host does not match
PUID 0-65536 Sets user ID for container
PGID 0-65536 Sets group ID for container

For more information on how to attach a barcode scanner, see Using a physical barcode scanner

To pass an argument, use the -e function, eg:

docker run -d -v bbconfig:/config -e ATTACH_BARCODESCANNER=true -p 80:80 -p 443:443 f0rc3/barcodebuddy-docker:latest

If you want to use a different internal URL for connecting to Grocy, enter the internal URL in during the setup. You can then set an external URL for links on the website with the argument

-e BBUDDY_EXTERNAL_GROCY_URL=your.url

Bare Metal

Requirements

  • webserver (eg. NGINX, Apache)
  • curl
  • Access to the command line
  • PHP 7.2 or higher (PHP 8.0 not supported at the moment)
  • The following PHP modules:
    • curl
    • date
    • json
    • redis
    • sqlite3
    • sockets
  • When using a barcode scanner:
    • Root access!
    • sudo
    • screen
    • evtest

Installation

Stable indicates, that you are using the latest release which should work without any bugs. Unstable is the latest developer version, which might include more features, but could also contain bugs.

It is strongly recommended to change pm.max_children to a value of 10 or higher in /etc/php7/php-fpm.d/www.conf (path might be different, depending on PHP version and distribution; for Ubuntu 18.04 it is /etc/php/7.2/fpm/pool.d/www.conf).

Webserver setup

This guide is written for a Debian based server, including Ubuntu. If you already have a webserver setup, please make sure to have a look at the Nginx example file, as for the folder /api/ a rewrite rule has to be added.

Installing NGINX
  • Get root, ideally with sudo -i

  • Install nginx: apt-get install nginx

  • If you are running a server with ufw active, run ufw allow 'Nginx Full'

  • Install all php modules and other requirements apt-get install php php-fpm php-curl php-date php-json php-sqlite3 php-redis redis redis-server sudo screen evtest

  • If some of the packages are not found, try again including the php version, eg. apt-get install php7.2-curl ... (see next point)

  • Check what PHP version you are using with php --version (eg. “7.2”).

  • Copy the Nginx example file to /etc/nginx/sites-enabled/

  • Adjust the new file:

    • If you are not using PHP7.2, change the line fastcgi_pass unix:/var/run/php/php7.2-fpm.sock; to your PHP version
    • If you are not installing Barcode Buddy to /var/www/html/barcodebuddy/, change the line root /var/www/html/barcodebuddy/; to your directory
  • Follow the steps below to download either the stable or unstable version

  • Execute the command chown www-data:www-data -R /path/to/the/barcodebuddy/folder for the folder that you just created

  • Change pm.max_children to a value of 10 in /etc/php/7.2/fpm/pool.d/www.conf (adjust path for your PHP version)

  • Restart NGINX service nginx restart

Configuring Apache2

We recommend using Nginx. If you are already an Apache2 user, follow these steps to make sure that Barcode Buddy is working correctly:

  • Execute a2enmod rewrite to make sure that the rewrite module is active
  • Make sure that you can use .htaccess files for rewriting. For that the option AllowOverride for the directory must be set to All. You can normally find this configuration in the apache2.conf file. For Ubuntu this file is located at /etc/apache2/apache2.conf. Search for AllowOverride and set it to All for the root directory where Barcode Buddy is installed.

Example:

[...]
<Directory /var/www/>
       Options Indexes FollowSymLinks
       AllowOverride All
       Require all granted
</Directory>
[...]

Stable version

Download the project and copy all files into your webserver.

Unstable version

Execute

git clone https://github.com/Forceu/barcodebuddy.git .

in the folder where you want to install Barcode Buddy to.

Starting the websocket service

If you have access to your webservers command line, make sure to start the websocket server. This way you can use the Screen module and if there are any changes, Barcode Buddy will automatically refresh.

Navigate to your installation folder and execute php wsserver.php to start the server. To have it run in the background, either use the screen application (recommended)

screen -S bbuddyserver -d -m /usr/bin/php /path/to/the/barcodebuddy/folder/wsserver.php

or the following command:

nohup php wsserver.php &

To start the websocket server after a reboot, you can use cron. Make sure to use the crontab for the webserver user (on Debian/Ubuntu this the user www-data.

Open the crontab for the user:

sudo crontab -e -u www-data

And insert the following new line (you might need to adjust the paths):

@reboot /usr/bin/screen -S wsserver -d -m /usr/bin/php /var/www/html/barcodebuddy/wsserver.php

VirtualBox

We have also released a VirtualBox image, which automatically downloads the latest docker image and runs it.

Installation

Open VirtualBox, and go to File/Host Network Manager. If there is no network listed yet, click on “Create” and make sure that the box for DHCP Server is ticked. Download the image and open it with VirtualBox, then click on “Import” in the new window.

Start the image - once it is completely running, you will see a login prompt. Above that, you will see two IP addresses. Normally with the second one you can reach the server, so simply connect in your webbrowser to http://THE_IP/.

If you need to log in to the image, the default username is root and the default password is barcode. For security reasons, SSH is disabled, to enable it, execute rc-update add sshd (make sure to change your password and to add a non-root user!)

Reverse Proxy

If you would like to run Barcode Buddy behind a reverse proxy, you can find an Nginx configuration in the example folder.

Make sure that you set fastcgi_pass_header "X-Accel-Buffering" in the Barcode Buddy host Nginx configuration, or proxy_buffering off in the reverse proxy configuration. If buffering is enabled for your reverse proxy, Server-Sent Events (SSE) might not be available and would break the Screen module.

Hass.IO

Connecting to Grocy

If you are running Grocy in a HASS.io container, further configuration is needed. Open HASS and go to the Grocy plugin section (not Grocy itself). Scroll down and enter 9192 in the Network section and press save. Make sure that you disable SSL in the Grocy config section above, if you are not using a proper certificate. Then restart Grocy. You will now be able to access Grocy under the URL http://hassio.local:9192. In Barcode Buddy setup, enter http://hassio.local:9192/api/ as URL.