search

nanawel / our-shopping-list

OSL is a simple shared list web-application based on Node and VueJS. Typical uses include shopping lists of course, and any other small todo-list that needs to be used collaboratively.
GNU Affero General Public License v3.0
82 stars 8 forks source link
collaborative mongodb nodejs pwa todolist vuejs websocket

readme

<img src="client/src/assets/logo.png" alt="OSL logo" title="Our Shopping List" align="right" height="120" />

Our Shopping List

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:

But, at this date it lacks the following:

⭐ New in v2: Boards feature

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.

☝ Instructions when migrating from v1 to v2

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!

If you want to keep using one single board on your instance (just like on v1)

If you want to enable the new boards feature and migrate your existing lists to a dedicated board

🖼 Screenshots

Mobile

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

Click here to see more!

Desktop

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

Click here to see more!

📦 Installation

🐋 With Docker

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

🐋 With 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

Robots.txt

By 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.

🗒 Notes for reverse-proxy (SSL offloading)

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.

Apache

<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]

Nginx

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;
}

⚠ Notes when serving multiple instances on different web roots

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:

Debugging on server side

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=*

Upgrade MongoDB to 7.x

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

👷 Developer installation

🐋 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

Translation

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/

Special cases

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.

Upgrade MongoDB to 7.x

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