OSL is a simple shared list application. Typical uses include shopping lists of course, and any other small todo-list that needs to be used collaboratively.
The current implementation provides the following features:
VUE_APP_SINGLEBOARD_MODE
)But, at this date it lacks the following:
Before v2, all of the lists on an instance were available to all users.
Version 2 introduces a new feature called "boards". It's simply a way to group lists together under a common name. That name can then be shared so that people use the lists from a board collaboratively.
But, you might want to disable that feature and keep using a unique board for
your whole instance. In that case, just use the provided
VUE_APP_SINGLEBOARD_MODE
environment variable.
But have no fear, you can always:
See next § for instructions on how to enable one mode or the other.
Version 2 has added the multiboard feature which changes the default mode the application runs into.
If you already had a working v1, and would like to upgrade to v2 please follow the steps below:
⚠ Back up your data before proceeding!
VUE_APP_SINGLEBOARD_MODE
to 1
docker-compose exec app node cli.js board:create --singleboard
docker-compose exec app node cli.js list:move-to-board --all --singleboard
VUE_APP_SINGLEBOARD_MODE
is not set or set to 0
# Get the created board's slug from the output and use it in the following command
docker-compose exec app node cli.js board:create my-board
docker-compose exec app node cli.js list:move-to-board --all --board my-board
☝ Screenshots are from v1, but v2 looks mostly the same.
☝ Screenshots are from v1, but v2 looks mostly the same.
With a running MongoDB container as
mymongo
on the host:
docker run --detach \
--name our-shopping-list \
--link mymongo:mongodb \
--publish 80:8080 \
ourshoppinglist/our-shopping-list
docker-compose
Use the provided docker-compose.yml
and adapt it to
your needs.
Then to start the containers:
docker-compose up -d
Available environment variables for the app
container
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/
)MongoDB authentication is not supported yet.
Application keys
VUE_APP_APM_ENABLED
(default: 0
) ReferenceVUE_APP_APM_LOGLEVEL
(default: warn
) ReferenceVUE_APP_APM_SERVERURL
(default: http://localhost:8200
) ReferenceVUE_APP_APM_SERVERURLPREFIX
(default: /intake/v${apiVersion}/rum/events
) ReferenceVUE_APP_APM_SERVICENAME
ReferenceVUE_APP_BOARD_DELETION_ENABLED
(default: 0
) ReferenceVUE_APP_CHECKED_ITEMS_HISTORY_SORT_FIELD
(default: lastCheckedAt
, see available fields here)VUE_APP_CHECKED_ITEMS_HISTORY_SORT_ORDER
(default: desc
)VUE_APP_CLIENT_LOG_CONSOLE_ENABLED
(default: false
, see doc here)VUE_APP_CLIENT_LOG_ENABLED
(default: false
, see doc here)VUE_APP_CLIENT_LOG_LEVEL
(default: debug
)VUE_APP_EDIT_ITEM_ON_CREATE
(default: 0
)VUE_APP_HOME_MESSAGE
(default: empty)VUE_APP_I18N_FALLBACK_LOCALE
(default: en
)VUE_APP_I18N_FORCE_LOCALE
(default: 0
)VUE_APP_I18N_LOCALE
(default: en
)VUE_APP_LIST_ALL_BOARDS_ENABLED
(default: 0
, has no effect in singleboard mode)VUE_APP_LOCALSTORAGE_KEY_PREFIX
(default: OurShoppingList_
)VUE_APP_SHORT_TITLE
(default: OSL
)VUE_APP_SINGLEBOARD_MODE
(default: 0
)VUE_APP_SOCKETIO_CSR_MAXDISCONNECTIONDURATION
(default: 1800000
= 30mn)VUE_APP_SOCKETIO_PING_INTERVAL
(default: 25000
= 25sec.)VUE_APP_SOCKETIO_PING_TIMEOUT
(default: 20000
= 20sec.)VUE_APP_TITLE
(default: Our Shopping List
)VUE_APP_USE_ITEM_QUICK_SYNTAX
(default: 0
) ReferenceBy default, the embedded robots.txt
prevents search engines from browsing the application:
User-agent: *
Disallow: /
You can change this behavior by mounting the robots.txt
of your choice at /app/robots.txt
in the container.
OSL uses a WebSocket to allow server-to-client communication. So using a reverse-proxy to forward the connection implies the presence of the following sections below in the corresponding virtual host.
Replace 127.0.0.1
and 8080
with the IP of the OSL host if your RP is not
the 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 On
RewriteEngine On
RewriteCond %{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 the BASE_URL
variable to the matching web root on each instance.
Make sure you set VUE_APP_LOCALSTORAGE_KEY_PREFIX
to a unique value too, otherwise clients switching from
one instance to another might corrupt the internal cache in their browser.
Example:
BASE_URL
= public-osl/
VUE_APP_LOCALSTORAGE_KEY_PREFIX
= OSL1_
BASE_URL
= private-osl/
VUE_APP_LOCALSTORAGE_KEY_PREFIX
= OSL2_
You can use the standard DEBUG
environment variable to enable the verbose mode of the server:
Example to log all operations related to socket-io (WebSocket) and the URL rewrite process
(when using a custom BASE_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 with mongo:4
but this version
of 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-compose exec -T mongodb mongodump -d osl --archive > osl-backup.archive
bash doc/update-mongo7.sh
🐋 This method also uses Docker, but with the local source files mounted into the
node
container.
First of all, clone this project in the directory of your choice. Then from it:
make dev-pull
make dev-init
make 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/*
requests and 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 the client/src/locales/
directory.
If you want to translate OSL in a new language, feel free to add your contribution using
Weblate.
Register on Weblate and go to https://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 bundle in "production" mode.
Here's how:
make dev-shell
cd 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 app with TLS enabled. Use the
ENABLE_TLS
variable to use the embedded TLS proxy if needed.
Use the provided automated script as follows:
export COMPOSE_FILE=docker-compose.dev.yml
export DOCKER_COMPOSE_FILE=docker-compose.dev.yml
bash doc/update-mongo7.sh