Advanced usage and configuration

Further configuration

config.php

Once you started Barcode Buddy for the first time, you will find the file config.php in the folder data. This file is for further configuration - the following values can be changed:

Argument Value Effect Default
PORT_WEBSOCKET_SERVER 1024-65535 The port that the websocket server listens to. Change if you running multiple instances or the default port is already used by another application. 47631
DATABASE_PATH A writable path The path were the database file is written to. Make sure that the webserver does not allow the download of the file. Path includes filename. ./data/barcodebuddy.db
CURL_TIMEOUT_S 5-60 How long to wait for a request 20
CURL_ALLOW_INSECURE_SSL_CA true/false Accept self-signed SSL certificates false
CURL_ALLOW_INSECURE_SSL_HOST true/false Accept SSL certificates where the host does not match false
REQUIRE_API_KEY true/false Require API key for authentication when using API true
DISABLE_AUTHENTICATION true/false Disables user management, if enabled, Barcode Buddy will not ask for local username/password false
IS_DEBUG true/false Enable verbose error messages. If you think something is wrong, you can enable this and send a bugreport false
HIDE_LINK_GROCY true/false Set to true to remove the link to Grocy in the top header false
HIDE_LINK_SCREEN true/false Set to true to remove the link to the Screen module in the top header false
EXTERNAL_GROCY_URL null or URL If you are using an internal URL for API communication to Grocy, but require a different URL for external access, you can enter the URL here. (Replaces URL in top header) null
AUTHENTICATION_BYPASS_NETS array List of IPs and subnets that can bypass authentication. If using with a reverse proxy, ensure TRUSTED_PROXIES is set correctly empty
TRUSTED_PROXIES array List of IPs and subnets that will be trusted for X-Forwarded-For header information empty
SEARCH_ENGINE String URL for searchengine to use when manually looking up barcode https://google.com/search?q=
BASEURL String Option to add a baseurl if you are running Barcode Buddy behind a proxy /
OVERRIDDEN_USER_CONFIG mapped array To override settings that can be set in the UI, uncomment the specific line. Overridden values cannot be changed in the UI afterwards empty

Note: config.php is a copy of config-dist.php in the root directory, which is tracked by version control, but not included by php. Any changes in config-dist.php will be ignored by Barcode Buddy

configProcessing.inc.php

If you need to change the paths of the config.php or the user database location, you can do this in the configProcessing.inc.php file, found in the incl folder. As editing the file might break updating Barcode Buddy, it is rather recommended to use Environment variables instead of editing this file. The following values can be changed:

Argument Value Effect Default
CONFIG_PATH A writable path The path were the config.php file is written to. Path includes filename. ./data/config.php
AUTHDB_PATH A writable path The path were the user database file is written to. Make sure that the webserver does not allow the download of the file. Path includes filename. ./data/users.db

Environment variables

Environment variables can be passed to Barcode Buddy - that way you can configure it without editing any files.

All const declarations found in config.php can be passed as an environment variable, but must have the prefix BBUDDY_.

Example: To disable authentication, you need to set DISABLE_AUTHENTICATION to true. Therefore you need to pass the variable BBUDDY_DISABLE_AUTHENTICATION with the value true (see Passing environment variables to Barcode Buddy)

Note: OVERRIDDEN_USER_CONFIG is declared as an array in config.php. This is the only environment variable you need to pass as an array with the delimiter ;.

Example: To set the Grocy API details you need to declare GROCY_API_URL and GROCY_API_KEY. As you can see in config.php, they are part of the OVERRIDDEN_USER_CONFIG declaration (basically all configurations that can be changed through the web ui are part of that). You therefore need to pass the environment variable OVERRIDDEN_USER_CONFIG with the value GROCY_API_URL=https://myurl/api/;GROCY_API_KEY=1234

Passing environment variables to Barcode Buddy

Docker

Pass the variable with the -e argument. Example for disabling authentication and setting curl timeout to 30:

docker run -d -v bbconfig:/config -e BBUDDY_DISABLE_AUTHENTICATION=true -e BBUDDY_CURL_TIMEOUT_S=30 -p 80:80 f0rc3/barcodebuddy-docker:latest

Example for passing API details:

docker run -d -v bbconfig:/config -e BBUDDY_OVERRIDDEN_USER_CONFIG="GROCY_API_URL=https://myurl/api/;GROCY_API_KEY=1234" -p 80:80 f0rc3/barcodebuddy-docker:latest

Bare Metal

You need to add the variable to your Nginx configuration that you created in Webserver setup. For each environment variable, add the following line in the location ~ \.php$ block:

fastcgi_param BBUDDY_XXXXX 'value';

Example: Disabling authentication and setting curl timeout to 30:

[...]
location ~ \.php$ {
        fastcgi_param BBUDDY_DISABLE_AUTHENTICATION 'true';
        fastcgi_param BBUDDY_CURL_TIMEOUT_S '30';
        fastcgi_read_timeout 80;
        include fastcgi_params;
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
}
[...]

Example: Passing API details:

[...]
location ~ \.php$ {
        fastcgi_param BBUDDY_OVERRIDDEN_USER_CONFIG 'GROCY_API_URL=https://myurl/api/;GROCY_API_KEY=1234';
        fastcgi_read_timeout 80;
        include fastcgi_params;
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
}
[...]

API

Barcode Buddy offers an API that can be reached at http(s)://your.bbinstall.url/api. By visiting the URL, you will get current the documentation website with an overview of all API functions.

Interacting with the API

Unless disabled, all API calls will need an API key as authentication. A key can be generated in the web UI in the menu “API”. The API key needs to be passed in the body or can be added as a GET variable. Example getting info with curl:

curl -X GET -H "BBUDDY-API-KEY: myApiKey" "https://your.bbuddy.url/api/system/info"

Manually getting the info by adding the GET variable:

https://your.bbuddy.url/api/system/info?apikey=myApiKey

All functions that require parameters (except /action/scan ), expect them as a form/post parameter. Example: Setting the current mode to STATE_PURCHASE (2):

curl -X POST -H "BBUDDY-API-KEY: [[apiKey]]" -F 'state=2' "https://your.bbuddy.url/api/state/setmode"

Non-standard API: /action/scan

As mentioned above, the /action/scan also looks for GET parameters, in addition to the regular form/post parameters. This is to make it easier for scripts / apps to pass barcodes to Barcode Buddy.

Instead of the POST parameter barcode you can also pass the GET parameter add or text instead. Example Passing the barcode 123456 by just requesting the URL:

https://your.bbuddy.url/api/action/scan?apikey=myApiKey&add=123456

Plugins

Barcode Buddy offers plugin support. All PHP scripts in the folder plugins are automatically loaded. See also the example script .