streetmerchant/docs/getting-started.md

Getting started

You do not need any computer skills, smarts, or anything of that nature. You are very capable as you have made it this far. Some basic understanding how a terminal, git, and or Node.js is a bonus, but that does not limit you to getting streetmerchant running!

Prerequisites

• git
• Either Node.js 14 or Docker (1.13.0+) (advanced users)

Using Node.js

Reference	Note
tag	Example, v1.0.0; stable
main	Latest HEAD; not tagged, could be unstable

1. Download Node.js 14
2. Clone this project git clone https://github.com/jef/streetmerchant.git.
   1. To checkout a particular reference, use git checkout <ref name> after cloning.
3. Navigate to this project by entering cd streetmerchant.
4. Run npm install.
5. Make a copy of dotenv-example and name it dotenv.
6. Edit the dotenv file to your liking using a text editor (like vscode).
7. Run npm run start to start.

At any point you want the program to stop, use ++ctrl+c++.

???+ tip Community based help can also be found on the wiki. Feel free to check that out if you're having problems running. If you're still having problems running, you're probably not the first. Make some searches through the GitHub issues before making one.

Using Docker

Available via GitHub Container Registry.

Tag	Note
latest	Latest release; stable
nightly	Latest HEAD each day at midnight UTC; could be unstable

# to run docker nightly
docker run -it --rm \
  --env-file ./dotenv \
  ghcr.io/jef/streetmerchant:nightly

# to test notifications
docker run -it --rm  \
  --env-file ./dotenv \
  ghcr.io/jef/streetmerchant:nightly test:notification:production

See Developing in docker for more information

Customization

To customize streetmerchant, make a copy of dotenv-example as dotenv and make any changes to your liking. View Reference for more information on variables and their usage.

???+ tip All environment variables are optional.

For developers

Developing in Node.js

The command npm run start:dev can be used instead of npm run start to automatically restart the project when filesystem changes are detected in the src/ folder or dotenv file.

Use npm run lint to see any linting uses and npm run fix to automatically fix the issues it can.

Developing in Docker

Prerequisites

• Docker (1.13.0+)
• GNU Make
  • Optional, but increases quality of life
• Docker Compose
  • Depending on your system, you may already have this. Check before installing.

Starting with docker-compose

1. Make a copy of dotenv-example and name it dotenv.
2. Edit the dotenv file to your liking using a text editor (like vscode).
3. If you're using make, you can run make run to start and make stop to stop.
   1. There are more options in the Makefile, feel free to explore.
4. If you do not have make, you can run docker-compose directly:

# To start
# Use `-d` if you want to run in detached mode
# Use `--build` if you want to build the image before running (default image is latest in GitHub Container Registry).
docker-compose up

# To break down
docker-compose down

???+ note If you are using WEB_PORT, then you will need to add the following to docker-compose:

```
ports:
  - "<WEB_PORT>:<WEB_PORT>"
```

Replace `<WEB_PORT>` with the value you gave in your `dotenv`.