mirror of https://github.com/kcal-app/kcal.git
150 lines
4.3 KiB
Markdown
150 lines
4.3 KiB
Markdown
# kcal – the personal food nutrition journal
|
||
[](https://github.com/kcal-app/kcal/actions/workflows/ci.yml)
|
||
[](https://coveralls.io/github/kcal-app/kcal)
|
||
|
||
## Deployment
|
||
|
||
### Heroku
|
||
|
||
[](https://heroku.com/deploy)
|
||
|
||
After initial deployment the `APP_KEY` environment variable must be set as Heroku's
|
||
deploy button does not support the necessary format. This can be set one of two
|
||
ways:
|
||
|
||
### From App Settings
|
||
|
||
1. Navigate to the deployed app.
|
||
|
||
1. Click the "More" menu and select "Run console".
|
||
|
||
1. Enter the following command and click "Run".
|
||
|
||
php artisan --no-ansi key:generate --show
|
||
|
||
1. Copy the output from the command (it should start with `base64:`).
|
||
|
||
1. Close the console.
|
||
|
||
1. Navigate to the "Settings" tab, "Config Vars" section.
|
||
|
||
1. Click "Reveal Config Vars".
|
||
|
||
1. Enter a new config var with values:
|
||
|
||
- KEY: `APP_KEY`
|
||
- VALUE: *Paste console out copied from Step 4*
|
||
|
||
1. Click "Add"
|
||
|
||
The application will restart after setting the config var and login will work.
|
||
|
||
### Using Heroku CLI
|
||
|
||
With the Heroku CLI utility installed and connected to the app, execute:
|
||
|
||
heroku config:set APP_KEY=$(php artisan --no-ansi key:generate --show)
|
||
|
||
## Search :mag:
|
||
|
||
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](https://www.algolia.com/users/sign_in) to an Algolia account.
|
||
|
||
1. Create an application for kcal.
|
||
|
||
1. Navigate to the application's "API Keys" section.
|
||
|
||
1. 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.
|
||
|
||
1. 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.
|
||
|
||
1. 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](https://getcomposer.org/download/)
|
||
- [Docker](https://docs.docker.com/get-docker/)
|
||
- [Docker compose](https://docs.docker.com/compose/install/)
|
||
|
||
1. Clone the repository.
|
||
|
||
git clone https://github.com/kcal-app/kcal.git
|
||
|
||
1. Move in to the cloned folder.
|
||
|
||
cd kcal
|
||
|
||
1. Install development dependencies.
|
||
|
||
composer install
|
||
|
||
1. 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](https://thekelleys.org.uk/dnsmasq/doc.html) or something similar
|
||
configured for the `test` domain you can change this to `http://kcal.test`.
|
||
|
||
1. Generate an app key.
|
||
|
||
touch .env
|
||
php artisan key:generate
|
||
|
||
1. Run it! :sailboat:
|
||
|
||
vendor/bin/sail up -d
|
||
|
||
1. (On first run) Run migrations.
|
||
|
||
vendor/bin/sail artisan migrate
|
||
vendor/bin/sail artisan elastic:migrate
|
||
|
||
1. (On first run) Create the initial user.
|
||
|
||
vendor/bin/sail artisan db:seed --class UserSeeder
|
||
|
||
The default username and password is `admin@kcal.test`.
|
||
|
||
Once the application finishes starting, navigate to [http://127.0.0.1:8080](http://127.0.0.1:8080)
|
||
(or [http://kcal.test:8080](http://kcal.test:8080) if configured).
|