freesewing/markdown/dev/reference/repos/backend/en.md

title
backend

See also: The backend API reference

Our backend is a REST API built with Express, using MongoDB as our database.

This backend handles the storage and retrieval of user data. Including:

• User profiles
• Models
• Recipes

This backend does not include any code related to our patterns. It is only required if you want to use your own instance of freesewing.org.

Getting started

To start this backend, you'll need:

• A MongoDB database
• Configure environment variables (see configuration below)

There's a few different ways you can get started:

Using our docker image and your own database

If you just want the backend and provide your own mongo instance, you can run our docker image directly from the internet:

docker run --env-file .env --name fs_backend -d -p 3000:3000 freesewing/backend

Your backend will now be available at http://localhost:3000

Using docker-compose

You can use docker-compose to spin up both the backend API and a MongoDB instance. Clone the repository, and run docker-compose up:

git clone git@github.com:freesewing/backend.git
cd backend
docker-compose up

Your backend will now be available at http://localhost:3000

Run from source

To run the backend from source, you'll need to clone this repository and intall dependencies.

git clone git@github.com:freesewing/backend
cd backend
npm install
npm install --global backpack-core

We are installing backpack-core globally for ease-of-use

While developing, you can run:

npm run develop

And backpack will compile the backend, and spin it up. It will also watch for changes and re-compile every time. Handy!

If you want to run this in production, you should build the code:

npm run build

Then use something like PM2 to run it and keep it running.

Configuration

This backend can be configured with environment variables. We provide an example.env file that you can edit and rename to .env. This way they will be picked up automatically.

The available variables are listed below, as we as in our example.env file.

Variable	Description
FS_BACKEND	URL on which the backend is hosted
FS_STATIC	URL on which the static content is hosted
FS_STORAGE	Location on disk where to store files
FS_MONGO_URI	URL for the Mongo database
FS_ENC_KEY	Secret used for encryption of data at rest
FS_SMTP_HOST	SMTP server through which to send outgoing emails
FS_SMTP_PORT	Port to use to connect to the SMTP server
FS_SMTP_USER	SMTP relay username
FS_SMTP_PASS	SMTP relay password
FS_GITHUB_CLIENT_ID	Github client ID for Oauth signup/login via GitHub
FS_GITHUB_CLIENT_SECRET	Github client ID for Oauth signup/login via GitHub
FS_GOOGLE_CLIENT_ID	Google client ID for Oauth signup/login via Google
FS_GOOGLE_CLIENT_SECRET	Google client ID for Oauth signup/login via Google

Authentication

This API uses JWT for authentication. Authenticated calls to this API should include a Authorization header as such:

Authorization: Bearer <token>

The token is returned from the /login, /oauth/login, and /confirm/login endpoints.

CLI

Our backend encrypts data at rest using the mongoose-encryption plugin. That's a good thing, but can complicate life a bit when you'd like to go and in make some changes to the data without going through the application code. If you use some sort of administration tools for MongoDB and write data to the DB, that data won't be encrypted. And thus reading that data back will fail (since we expect encrypted data).

Because of this, this backend comes with a couple of command-line tools to do basic database tasks:

Command	Description
npm run clear:users	Remove all users
npm run clear:models	Remove all models
npm run clear:recipes	Remove all recipes
npm run clear:confirmations	Remove all confirmations
npm run clear:all	Empty the entire database
npm run clear:reboot	Empty database, then load sample data

Tip: You can use npm run cli to see the available options

Tests

There's two ways to run tests:

• npm run test will run tests that don't depend on emails

• npm run testall will runn all tests, including the ones that depend on email

To run the email tests, spin up a mailhog container with Docker:

sudo docker run -p 8025:8025 -p 1025:1025 mailhog/mailhog

Then, configure your backend as such:

FS_SMTP_HOST : localhost (this makes sure emails go to mailhog) FS_SMTP_PORT : 1025 (the mailhog port)

This allows complete end-to-end testing of signup flow and other things the depend on email sent to the user.

Links

• 💻 Maker site: freesewing.org
• 👩‍💻 Developer site: freesewing.dev
• 💬 Chat/Support: discord.freesewing.org
• 🐦 Twitter: @freesewing_org
• 📷 Instagram: @freesewing_org

License

Copyright (c) 2019 Joost De Cock - Available under the MIT license.

See the LICENSE file for more details.