#forage

A shopping list front-end for your (self-hosted) Mealie instance.

★ Releases ★ Bugs

Mealie is self-hosted recipe manager, meal planner, and shopping list web app. Forage is an application aimed to improve the shopping list experience of Mealie by providing a native (non-web) interface via the Mealie API.

With the release of v1, Forage can work entirely in offline mode without a server. Without a server, it functions as a non-connected shopping list app, albeit currently limited in editing.

There is a public chat available at #forage:matrix.org.

#Features & screenshots

Forage connects to your Mealie instance and shows you a list of all of your shopping lists. When you select one, it shows you the shopping list, which you can then check items off or add items to. Changes are sync'd back to your Mealie server.

• Runs on Linux, Android, Darwin, Windows, iOS, and FreeBSD (builds are provided for the first four)
• Native interface, not a repackaged web framework like PhoneGap.
• Selection & creation of lists
• Adding & completing (checking) items off a list
• Stays logged in
• Battery-friendly
• Concurrent list edit support (list change merging)
• Lists are sorted, with unchecked items at the top, and then lexically ignoring any initial units. E.g., "6 apples" will sort before "Banana" or "1 avocado".
• If Forage can't connect to your server to save changes, it retries occasionally until it can. Unless you exit Forage before the changes are saved, it will eventually succeed.
• Offline caching. Forage will persist data to the phone and still work in offline mode.

#Caveats

• Forage is built with Go and Fyne. Executables on desktop are 12MB, and Android APKs are 80MB. IMO this is pretty huge, but it's the price of the tooling.
• Fyne is like Swing: widgets and interactions are bespoke, not calls down to the underlying windowing widget GUI. You won't see a native-looking UI.
• There's a bug, on Android at least, where backspacing in text fields deletes two characters. The bug's been reported, and is (IMO) not a show-stopper, but be aware.

That said, it's not (IMO) ugly, and Fyne is surprisingly light on the battery. I haven't seen it yet near the top of battery use on my phone, or at the top of top on my laptop.

#How to...

#... use it

Enter your Mealie server URL and login credentials (user name & password). You can also create a token through the Mealie web UI and put that in for the password; in this case, leave the user name blank. Forage only uses user credentials to fetch a token.

Once logged in, you'll be presented with a list of all of the shopping lists defined on the server. Choose one of those, and you'll see a list of all shopping items in the list. You can check them off or add new items to the list; these changes are saved back to the server. If you want to change shopping lists, use the tab at the top to go back to the list-of-lists tab. You can change your server by going back to the Server tab.

#... get it

• Builds for Android are submitted to F-Droid.
• Binaries for Linux, Android, Mac, and Windows are provided here. Packages are signed with my (published) public key, and are compressed with zstd (you'll need to uncompress them after downloading). Submit a ticket if you'd like me to add other architectures; there are a lot of possible permutations, so I'm only adding them as requested.
• You can review the code and build it yourself if you'd like

I'm still figuring out how to compile for iOS on the automated build server. Apple does not make it easy.

My signing key is signed with my more venerable -- and more heavily validated -- personal key.

#... build it

The technologies aren't important, except when they are. Forage's UI is provided by Fyne, a cross-platform GUI toolkit for Go. As such, it does not provide a "native" experience, on any platform. OTOH, it doesn't look bad, and it allows compiling apps that work on Windows, Linux, Mac, iOS, and Android.

This may be your best bet, short-term, for getting an iOS build.

In any case, you need Go 1.17 or later. It may work with an earlier version. Once you check out the sourcecode, it should build with:

go build .

If you want to build an Android APK, make sure you have the Android NDK and Fyne installed. Installation for Android will vary with your OS/Distribution; on Arch, it's:

pacman -S android-ndk

And Fyne can be installed with:

go install fyne.io/fyne/v2/cmd/fyne@latest

Then call:

fyne package -os android

The icon is stored in the repo as SVG and needs to be converted to PNG before being used.

For iOS, you need to additionally have XCode installed, but you should then be able to run:

fyne package -os ios

This is untested as I don't have access to a modern Mac.

Finally, move the package to your device and install it. For Linux, I highly recommend mconnect and KDE Connect. They're excellent for OTA interactions between Android and Linux. For example, I do this on my laptop to move the APK over to my phone:

mconnectctl share-file /org/mconnect/device/2 forage.apk

#... contribute

I'm happy to review pull requests.

While I've set up the tracker for public requests, for my own purposes I used Legume to track bugs and todos. If you'd like to see what's on my mind, run leg in a check-out of the source.

There's a mock Mealie server in test/cmd. Run it with go run ./test/cmd; it listens on localhost:9999 and starts with a couple of lists, persisting changes to memory. Authentication is utterly missing, so you can't test that; in fact, if you supply a username/password combo, the Go OAuth2 library will fail, so put a value only in the password field. It doesn't matter what. The code used by this mock server is also used by the unit tests, exercised by go test ..

There's a command-line argument you can provide to mess with the batching time. Batching defaults to 30 seconds, and you can override it with the -T argument, which is in milliseconds. Set it to 0 and you'll disable the buffering. This is what the unit tests do.

#... get Mealie

Setting up your own Mealie server is beyond the scope of this README; I'm not directly associated with the project. However, I found it very easy to run using podman:

sudo mkdir /var/db/mealie
sudo chown $USER:$USER /var/db/mealie
sudo chmod ug+s /var/db/mealie
podman create --name=mealie -e TZ=America/Chicago -p 9284:80 \
   -v /var/db/mealie:/app/data --restart unless-stopped \
      docker.io/hkotel/mealie:latest
podman start mealie

I then proxied from Caddy to 9284. YMMV, so I'd recommend following instructions on Mealie's site.