Repository files navigation

OSL is a simpleshared list application. Typical uses includeshoppinglists of course, and any other small todo-list that needs to be usedcollaboratively.

The current implementation provides the following features:

• Multiple boards (can be disabled, seeVITE_APP_SINGLEBOARD_MODE)
• Each board withmultiple lists
• Real-time sync between users
• Items with the following fields: name, quantity, details
• Checkable items
• 2display modes for items (unchecked only / checked only, sorted by check time)
• Intuitivesearch
• Mobile-first UI with swipeable items
• PWA basic support
• Partial internationalisation (i18n)
  • Only EN and FR languages are available at that time, but PR are welcome for more!See exampleshere.

But, at this date it lacks the following:

• Full PWA support with offline mode and deferred sync

Before v2,all of the lists on an instance were available toall users.

Version 2 introduces a new feature called "boards". It's simply a way to grouplists together under a common name. That name can then be shared so thatpeople use the lists from a board collaboratively.

But, you might want to disable that feature and keep using a unique board foryour whole instance. In that case, just use the providedVITE_APP_SINGLEBOARD_MODE environment variable.

But have no fear, you can always:

• Switch fromsingleboard mode to multi-board
  • In that case you'll have tocreate a new board and choose it as target for existing lists with theprovided CLI tool.
• Switch from multi-board mode tosingleboard
  • In that case you can choose which lists to migrate to the specialunique board, but you'll lose access to all other lists (they are notdeleted, just not accessible anymore)

See next § for instructions on how to enable one mode or the other.

Version 2 has added themultiboard feature which changes the default modethe application runs into.

If you already had a working v1, and would like to upgrade to v2 please followthe steps below:

⚠Back up your data before proceeding!

• Make sure you set theVITE_APP_SINGLEBOARD_MODE to1
• Once started, use the CLI to migrate existing lists to the special boardused as common parent for lists in "singleboard" mode.

  docker composeexec app node cli.js board:create --singleboarddocker composeexec app node cli.js list:move-to-board --all --singleboard

• Use the application as usual (you might have to clear your browser's cacheto make sure there's no invalid data left).

• Make sureVITE_APP_SINGLEBOARD_MODE isnot set or set to0
• Create a new board with the name of your choice

  # Get the created board's slug from the output and use it in the following commanddocker composeexec app node cli.js board:create my-boarddocker composeexec app node cli.js list:move-to-board --all --board my-board

• Open the application, and from the home screen open the board you've just createdto find your lists.

☝ Screenshots are from v1, but v2 looks mostly the same.

Click here to see more!

☝ Screenshots are from v1, but v2 looks mostly the same.

Click here to see more!

With a runningMongoDB container asmymongo on the host:

docker run --detach \  --name our-shopping-list \  --link mymongo:mongodb \  --publish 80:8080 \  ourshoppinglist/our-shopping-list

Use the provideddocker-compose.yml and adapt it toyour needs.

Then to start the containers:

docker compose up -d

Available environment variables for theapp container

⚠️ The originalVUE_APP_ prefix has been replaced due to the migration to Vite.
You must now useVITE_APP_ instead.

• System keys

  • LISTEN_PORT (default:8080)
  • MONGODB_HOST (default:mongodb)
  • MONGODB_PORT (default:27017)
  • MONGODB_DB (default:osl)
  • BASE_URL (default:empty) Set to base path if your web root is not/ (ex:/my-osl/)
    • ⚠️ Not supported in development mode (Vite-related limitation)

  MongoDB authentication is not supported yet.

• Application keys

  • VITE_APP_APM_ENABLED (default:0)Reference
  • VITE_APP_APM_LOGLEVEL (default:warn)Reference
  • VITE_APP_APM_SERVERURL (default:http://localhost:8200)Reference
  • VITE_APP_APM_SERVERURLPREFIX (default:/intake/v${apiVersion}/rum/events)Reference
  • VITE_APP_APM_SERVICENAMEReference
  • VITE_APP_BOARD_DELETION_ENABLED (default:0)Reference
  • VITE_APP_CHECKED_ITEMS_HISTORY_SORT_FIELD (default:lastCheckedAt, see available fieldshere)
  • VITE_APP_CHECKED_ITEMS_HISTORY_SORT_ORDER (default:desc)
  • VITE_APP_CLIENT_LOG_CONSOLE_ENABLED (default:false,see doc here)
  • VITE_APP_CLIENT_LOG_ENABLED (default:false,see doc here)
  • VITE_APP_CLIENT_LOG_LEVEL (default:debug)
  • VITE_APP_EDIT_ITEM_ON_CREATE (default:0)
  • VITE_APP_HOME_MESSAGE (default:empty)
  • VITE_APP_I18N_FALLBACK_LOCALE (default:en)
  • VITE_APP_I18N_FORCE_LOCALE (default:0)
  • VITE_APP_I18N_LOCALE (default:en)
  • VITE_APP_LIST_ALL_BOARDS_ENABLED (default:0, has no effect insingleboard mode)
  • VITE_APP_LOCALSTORAGE_KEY_PREFIX (default:OurShoppingList_)
  • VITE_APP_SHORT_TITLE (default:OSL)
  • VITE_APP_SINGLEBOARD_MODE (default:0)
  • VITE_APP_SOCKETIO_CSR_MAXDISCONNECTIONDURATION (default:1800000 = 30mn)
  • VITE_APP_SOCKETIO_PING_INTERVAL (default:25000 = 25sec.)
  • VITE_APP_SOCKETIO_PING_TIMEOUT (default:20000 = 20sec.)
  • VITE_APP_TITLE (default:Our Shopping List)
  • VITE_APP_USE_ITEM_QUICK_SYNTAX (default:0)Reference

By default, the embeddedrobots.txt prevents search engines from browsing the application:

User-agent: *Disallow: /

You can change this behavior by mounting therobots.txt of your choice at/app/robots.txt in the container.

OSL uses a WebSocket to allow server-to-client communication. So using areverse-proxy to forward the connection implies the presence of the followingsections below in the corresponding virtual host.

Replace127.0.0.1 and8080 with the IP of the OSL host if your RP is notthe host itself and/or if you're using another port.

<Proxy *>    Allow from all</Proxy>ProxyPass         /  http://127.0.0.1:8080/ProxyPassReverse  /  http://127.0.0.1:8080/ProxyPreserveHost OnRewriteEngine OnRewriteCond %{HTTP:Upgrade} =websocket [NC]RewriteRule /(.*)           ws://127.0.0.1:8080/$1 [P,L]RewriteCond %{HTTP:Upgrade} !=websocket [NC]RewriteRule /(.*)           http://127.0.0.1:8080/$1 [P,L]

location / {    proxy_set_header    Host $host;    proxy_set_header    X-Real-IP $remote_addr;    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;    proxy_set_header    X-Forwarded-Proto $scheme;    proxy_pass          http://localhost:8080;    proxy_http_version  1.1;    proxy_set_header    Upgrade $http_upgrade;    proxy_set_header    Connection "Upgrade";        proxy_redirect      http://localhost:8080 https://ourshoppinglist.myhost;}

Remember to set theBASE_URL variable to the matching web root on each instance.

Make sure you setVITE_APP_LOCALSTORAGE_KEY_PREFIX to a unique value too, otherwise clients switching fromone instance to another might corrupt the internal cache in their browser.

Example:

• 1st instance onhttps://my.host/public-osl
  • BASE_URL =public-osl/
  • VITE_APP_LOCALSTORAGE_KEY_PREFIX =OSL1_
• 2nd instance onhttps://my.host/private-osl
  • BASE_URL =private-osl/
  • VITE_APP_LOCALSTORAGE_KEY_PREFIX =OSL2_
• etc.

You can use thestandardDEBUGenvironment variable to enable the verbose mode of the server:

Example to log all operations related tosocket-io (WebSocket) and theURL rewrite process(when using a customBASE_URL):

DEBUG=socket.io:server,express-urlrewrite

Or if you need to log everything:

DEBUG=*

From the original release until june 2024, the stack was shipped withmongo:4 but this versionof MongoDB is deprecated and you can safely upgrade to MongoDB 7 while keeping your existing data.

Use the provided automated script as follows:

# Make a backup with mongodump first!docker composeexec -T mongodb mongodump -d osl --archive> osl-backup.archivebash doc/update-mongo7.sh

🐋 This method also uses Docker, but with the local source files mountedinto thenode container.

First of all, clone this project in the directory of your choice. Then from it:

make dev-pullmake dev-initmake dev-upd

Now start the Webpack Development Server with

make dev-watch

If you don't, you'll get 504 errors in the console on/sockjs-node/* requestsand you won't get hot reloading on changes.

If you want to enter the container, just use

make dev-shell

Translations can be very easily added and improved using the files from theclient/src/locales/directory.

If you want to translate OSL in a new language, feel free to add your contribution usingWeblate.
Register on Weblate and go tohttps://hosted.weblate.org/projects/our-shopping-list/client-src-locales/

In development mode, the service worker is not enabled.To workaround this limitation, you may want to ponctually build the JS bundlein "production" mode.

Here's how:

make dev-shellcd client/NODE_ENV=production yarn build

Then reload the page in your browser and the SW should be activated.You have to make sure you are running the appwith TLS enabled. Use theENABLE_TLS variable to use the embedded TLS proxy if needed.

Use the provided automated script as follows:

export COMPOSE_FILE=docker-compose.dev.ymlexport DOCKER_COMPOSE_FILE=docker-compose.dev.ymlbash doc/update-mongo7.sh