kcal/README.md

kcal – the personal food nutrition journal

Track nutritional information about foods and recipes, set goals, and record a food journal to help along the way. Kcal is a personal system that focuses on direct control of inputs (as opposed to unwieldy user generated datasets) and a minimal, easy to use recipe presentation for preparing meals.

Table of Contents

• Demo
• Screenshots
• Deployment
  • Heroku
• Configuration
  • Search
• Development
  • Testing

Demo

A demo of kcal is available on Heroku. Login credentials are:

• Username: kcal
• Password: kcal

The demo instance resets every hour, on the hour.

Screenshots

Deployment

Heroku

The default username and password for a Heroku deployment is kcal/kcal.

Using Heroku CLI

For a manual deploy using Heroku CLI, execute the following after initial deployment:

heroku run php artisan migrate
heroku run php artisan user:add
heroku config:set APP_KEY=$(php artisan --no-ansi key:generate --show)

Media storage

⚠️ Storage (for recipe photos) is not supported on Heroku yet. ⚠️

Search drivers

See the Search section for information about supported drivers. Additional environment variable configuration is necessary when using any search driver other than the default ("null").

Redis Add-on

The Heroku Redis add-on can be added to the app and will work without any configuration changes. It is left out of the default build only because it takes a very long time to provision.

Configuration

Search 🔍

The "ingredient" (food or recipe) search for journal entries and recipe ingredients supports three different backends using the SCOUT_DRIVER environment variable. In all cases, always ensure that the SCOUT_DRIVER environment variable is only set once in kcal's .env file.

Currently, the food and recipe list searches do not take advantage of these search drivers. Support for those searches will be added if the Laravel JSON:API adds support for Scout (see: laravel-json-api/laravel#32).

Algolia (algolia)

1. Create and/or log in to an Algolia account.

2. Create an application for kcal.

3. Navigate to the application's "API Keys" section.

4. Using the Application ID and Admin API Key values, update kcal's .env file:

    SCOUT_DRIVER=algolia
    ALGOLIA_APP_ID=<APPLICATION_ID>
    ALGOLIA_SECRET=<ADMIN_API_KEY>
   

ElasticSearch (elastic)

1. Determine the host and port for your ElasticSearch service.

2. Update kcal's .env file.

    SCOUT_DRIVER=elastic
    ELASTIC_HOST=<HOST:PORT>
    ELASTIC_PORT=<PORT>
   

   Note: The ELASTIC_PORT variable is a convenience option specifically for Docker Compose configurations and is not strictly required.

3. Run Elastic's migrations.

    php artisan elastic:migrate
   

Fallback (null)

The fallback driver is a simple WHERE ... LIKE clause search on a couple of key fields. Results will not be ordered by relevance, and some fields will not be searched (e.g. the tags fields). Using one of the other options is highly recommended.

Set SCOUT_DRIVER=null in kcal's .env file to use the fallback driver.

Development

Laravel Sail

Prerequisites

• Composer
• Docker
• Docker compose

Steps

1. Clone the repository.

    git clone https://github.com/kcal-app/kcal.git
   

2. Move in to the cloned folder.

    cd kcal
   

3. Install development dependencies.

    composer install
   

4. Create a local .env file.

    cp .env.local.example .env
   

   Note: the default APP_URL setting is http://127.0.0.1. If you have dnsmasq or something similar configured for the test domain you can change this to http://kcal.test.

5. Generate an app key.

    php artisan key:generate
   

   Verify that the APP_KEY variable has been set in .env. If has not, run php artisan key:generate --show and copy the key and append in to the APP_KEY= line manually.

6. Run it! ⛵

    vendor/bin/sail up
   

7. (On first run) Run migrations.

    vendor/bin/sail artisan migrate
    vendor/bin/sail artisan elastic:migrate
   

8. (On first run) Seed the database.

    vendor/bin/sail artisan db:seed
   

   The default username and password is kcal / kcal.

Once the application finishes starting, navigate to http://127.0.0.1:8080 (or http://kcal.test:8080 if configured).

Testing

Ensure that Sail is running (primarily to provide ElasticSearch):

vendor/bin/sail up -d

Execute tests.

vendor/bin/sail artisan test --parallel

Caveats

In order to support parallel testing, tests are run using sqlite (even though Sail provides MySQL). To test with MySQL make a copy of phpunit.xml.dist as phpunit.dist and change:

<server name="DB_CONNECTION" value="sqlite"/>
<server name="DB_DATABASE" value=":memory:"/>

to

<server name="DB_CONNECTION" value="mysql"/>
<server name="DB_HOST" value="db"/>

Now running vendor/bin/sail artisan test will run tests with MySQL but tests cannot be run in parallel.