UpSwyng is a mobile-ready, digital directory of resources to assist the unhoused and at-risk communities. This is a Code For Boulder project coming soon to Boulder County, Colorado.

Getting Started

If you have any issues getting started using these directions, please see the Troubleshooting section.

Requirements

Make sure you have these tools installed before you begin.

• Node.js version 14.3

• Docker version 20.10 or above

• Yarn

Building your local dev environment

1. Clone (or fork and clone) this repository and cd into it

2. Make sure docker is running on your machine. You can check by running docker ps in your terminal

3. Run yarn start:local

Project Organization

UpSwyng is a monorepo managed with Yarn Workspaces. It consists of five packages all in the packages directory:

• common - contains common libraries and utilities used across the other packages
• types - contains the TypeScript definitions used across the project
• server - a Sapper application with two parts:
  • an API server which provides data to the UpSwyng clients
  • an admin web interface which uses the Svelte framework to create and modify data for the project
• web - contains the React web client
• native - contains a proof-of-concept React Native client

Working With Yarn Workspaces

To run a command in a specific package, use the yarn workspace command from the project root. For example, to start the web package development server run:

yarn workspace @upswyng/web start

To run the same command in all workspaces, use yarn workspaces. For instance, to run test in all packages use:

yarn workspaces run test

Typing out the full workspace name can get tedious. You can place aliases in your .bashrc or .profile to save time:

alias @uw="yarn workspace @upswyng/web "

Now you only need @uw start to start the web dev server.

Running tests

When you push a branch up to GitHub, travis will attempt to build the app with your changes and will run our entire test suite to ensure that nothing is broken. It's a good idea to run tests locally before pushing, although it is not required.

If you wish to run tests locally, you will need to ensure that redis-server is available in your path. You can check by running redis-server, and you can install it here or via brew install redis on mac.

Once Redis is installed, run our entire test suite with yarn test.

Windows 10 Installation on Windows Subsystem for Linux 2

1. First Install WSL2 choosing Ubuntu or distribution of choice.
2. Install NVM to allow for different versions of Node. This will also install NPM.
3. Install yarn globally
4. Install Docker Desktop for Windows with WSL2 support. Note that it's important to do this after installing WSL2.
5. Fork or clone the repository into a folder native to Linux and not the Windows system. This avoids problems with line ending differences between Windows and Linux. It is also much faster to access the Linux filesystem directly rather than the Windows filesystem through Linux.
6. Run yarn start:local as noted above.

Troubleshooting

The engine "node" is incompatible with this module.

When running yarn to install project dependencies, you may see a message that looks similar to:

The engine "node" is incompatible with this module. Expected version "^14.3.x". Got "11.15.0".

This just means that your machine's current version of node does not match the version required to run the UpSwyng server, 14.3.x. To fix this you'll need to install and which your current version of Node. nvm is a helpful tool, among others, you could use to easily switch between node versions.

Type Errors

The packages native, server, and web depend on common and types. If you edit common or types, or pull a new commit which contains edits to those packages, they need to be rebuilt. If you do not rebuild, you may see a type error like:

upswyng/packages/server/src/utility/slackbot.ts(76,23): semantic error TS2551:
Property 'DraftApproved' does not exist on type '{ alert_live: any; draft_approved: any;
draft_created: any; draft_deleted: any; resource_issue_reopened: any; resource_issue_resolved: any;
user_permission_changed: any; }'. Did you mean 'draft_approved'?

To fix this, run the script:

yarn build:local-packages

Connection refused to server and database when using WSL2 and Ubuntu

When setting up the environment on Ubuntu the following errors may occur when executing yarn start:local

[ioredis] Unhandled error event: Error: connect ECONNREFUSED 127.0.0.1:6380

MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

To fix this issue make sure that you have properly installed the docker engine. steps for installation can be found at the Docker Engine installation docs.

Now install Docker Desktop. Documentation found here.

Once you have finished setting up Docker Desktop restart your computer and navigate to your upswyng folder, and run the following scripts.

yarn reset
yarn
yarn start:local

Reset

If nothing you try is fixing your issue, you can totally reset your local environment with yarn reset. After performing a reset, try yarn start:local and see if things work out.

Contributing

Pull requests are welcome and encouraged! Please review and follow our guidelines.