{"id":23143618,"url":"https://github.com/digitalinteraction/poster-vote-backend","last_synced_at":"2025-04-04T12:14:42.982Z","repository":{"id":38402514,"uuid":"360195363","full_name":"digitalinteraction/poster-vote-backend","owner":"digitalinteraction","description":"The Node.js based server for Poster Vote","archived":false,"fork":false,"pushed_at":"2023-05-05T08:57:47.000Z","size":2794,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-09T22:11:18.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://postervote.openlab.ncl.ac.uk/api/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalinteraction.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-21T14:12:43.000Z","updated_at":"2024-11-08T12:31:54.000Z","dependencies_parsed_at":"2025-02-10T13:31:31.533Z","dependency_job_id":null,"html_url":"https://github.com/digitalinteraction/poster-vote-backend","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fposter-vote-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fposter-vote-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fposter-vote-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fposter-vote-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalinteraction","download_url":"https://codeload.github.com/digitalinteraction/poster-vote-backend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174467,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T15:13:51.202Z","updated_at":"2025-04-04T12:14:42.961Z","avatar_url":"https://github.com/digitalinteraction.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PosterVote backend\n\nThis is the repo for the PosterVote backend source code.\nIt is an [Express](https://expressjs.com/) server written in [TypeScript](https://www.typescriptlang.org/) and deployed through [Docker](https://www.docker.com/).\nIt connects to a [MySQL](https://www.mysql.com/) database and uses migrations to manage tables.\nIt also has a CLI to perform migrations and perform other useful tasks.\n\n[What is PosterVote?](https://github.com/digitalinteraction/poster-vote)\n\n\u003c!-- toc-head --\u003e\n\n## Table of contents\n\n- [Development](#development)\n  - [Setup](#setup)\n  - [Regular use](#regular-use)\n  - [Code Structure](#code-structure)\n  - [Testing](#testing)\n  - [Formatting](#formatting)\n- [Deployment](#deployment)\n  - [Building the image](#building-the-image)\n  - [Using the image](#using-the-image)\n  - [Endpoints](#endpoints)\n  - [Using the cli](#using-the-cli)\n- [Future Work](#future-work)\n\n\u003c!-- toc-tail --\u003e\n\n## Development\n\n### Setup\n\nTo develop on this repo, you will need to have [Docker](https://www.docker.com/get-started) and [Node](https://nodejs.org/en/) installed on your dev machine.\n\nYou will also need a [SendGrid API key](https://app.sendgrid.com/settings/api_keys) to send authentication emails.\n\n```bash\n# Install dependencies through npm\nnpm install\n\n# Setup your environment, filling in the blanks\ncp .env.example .env\nnano .env\n```\n\n### Regular use\n\n```bash\n# Spin up a mysql database for development\n#  -\u003e Launches a mysql docker container\n#  -\u003e Access from the host with mysql://user:secret@127.0.0.1:3306/postervote\n#  -\u003e It uses a named volume so if you stop the container, the data persists\n#  -\u003e NOTE: The first time you run this you have to add a 'postervote' table\ndocker-compose up -d\n\n# Run a development server on your machine\n# -\u003e This will watch for changes to .ts files and reload the server\n# -\u003e It will fail if any config is missing in your .env\nnpm run dev\n\n# Run unit tests\n#  -\u003e It looks for files that end with '.spec.ts', e.g. MyApp.spec.ts\nnpm test -s\n\n# Generate the table of contents for this readme and docs/api.md\nnpm run gen-toc\n```\n\n### Code Structure\n\n| Folder         | Use                                                       |\n| -------------- | --------------------------------------------------------- |\n| bin            | Reusable commands for development, used in `package.json` |\n| dist           | Where TypeScript files are transpiled to                  |\n| src            | The location of the source code                           |\n| src/core       | Core utilities of the server                              |\n| src/migrations | Database migrations to create \u0026 replicate the database    |\n| src/routes     | Api routes, routed to by express                          |\n| src/views      | Pug templates for rendering html                          |\n| static         | Static assets served at `/static`                         |\n| uploads        | Internal uploads directory for storing files              |\n\n### Testing\n\nThis project uses [unit tests](https://en.wikipedia.org/wiki/Unit_testing) to ensure that everything is working correctly, guide development, avoid bad code and reduce defects.\nTests are any file in `src/` that ends with `.spec.ts`, by convention they are inline with the source code,\nin a parallel folder called `__tests__`.\n\n```bash\n# Run the tests\nnpm test -s\n\n# Generate code coverage\nnpm run coverage -s\n```\n\n### Formatting\n\nThis repo uses [Prettier](https://prettier.io/) to automatically format code when you stage changes.\nThis means that code that is pushed is always formatted to a consistent standard.\nYou can manually run the formatter with `npm run format`.\n\n## Deployment\n\n### Building the image\n\nThis project uses a [GitLab CI](https://about.gitlab.com/product/continuous-integration/) to build a Docker image when you push a git tag.\nThis is designed to be used with the `npm version` command so all docker images are semantically versioned.\n\n```bash\nnpm version ... # major | minor | patch\ngit push --tags\n```\n\n### Using the image\n\nWith this docker image you can easily deploy it to your server using docker-compose.\nThe server uses environment variables to let you configure how it works.\nSome variables are set by default when in `development` mode, below is the available configuration:\n\n| Variable           | Description                                                                          |\n| ------------------ | ------------------------------------------------------------------------------------ |\n| NODE_ENV           | The mode the server is running in either `production` or `development`               |\n| API_URL            | The url where this container is hosted, e.g. `https://api.postervote.co.uk`          |\n| WEB_URL            | The url where the web counterpart is hosted                                          |\n| DB_TYPE            | (optional) The type of database to conenct to, default: `mysql`                      |\n| DB_URI             | The uri to access the database, e.g. `mysql://user:secret@127.0.0.1:3306/postervote` |\n| JWT_SECRET         | A unique secret used to generate JWT tokens, the longer the better                   |\n| COOKIE_SECRET      | A unique secret used to sign cookies, the longer the better                          |\n| HASH_SECRET        | A unique secret used to hash private info with, the longer the better                |\n| ADMIN_EMAIL        | The email address where login emails will come from                                  |\n| SENDGRID_TOKEN     | Your [SendGrid API key](https://app.sendgrid.com/settings/api_keys)                  |\n| REG_TWILIO_NUMBER  | Your Twilio phone number used to register posters                                    |\n| VOTE_TWILIO_NUMBER | Your Twilio phone number used to submit votes                                        |\n\n### Endpoints\n\nSee [docs/api](/docs/api.md)\n\n### Using the cli\n\nYou can use the api with `docker run` or `docker exec`, depending if you have a running container already.\n\n```bash\n# If you have a running container\ndocker exec -it postervote_api cli --help\n\n# If you want to run without a container\n# -\u003e Where you have a mysql container and your (^) variables in .env\nIMAGE=openlab.ncl.ac.uk:4567/poster-vote/node-backend:1.3.1\ndocker run -it --rm --link mysql --env-file=.env $IMAGE cli --help\n```\n\nBelow is is the `--help` output for reference\n\n```\nUsage: cli [options] [command]\n\nOptions:\n  -V, --version                      output the version number\n  -h, --help                         display help for command\n\nCommands:\n  serve                              Run the server\n  db:migrate                         Perform database migrations (oldest to newest)\n  db:destroy                         DANGER: Undo database migrations (newest to oldest)\n  db:regenerate                      DANGER: Undo database migrations then perform them again\n  jwt:token \u003cemail\u003e                  Generate a JWT for a given email\n  bulk:append \u003cinput-file\u003e \u003cdevice\u003e  Start or append-to a bulk upload file\n  bulk:insert \u003cinput-file\u003e           Bulk register posters\n  help [command]                     display help for command\n```\n\n### Serial bulk\n\nThere are `bulk:append` and `bulk:insert` commands for bulk registering PosterVote devices agains poster records.\nThe first command generates/appends to an [ndjson](http://ndjson.org/) for each device connected to over serial.\nThe second command takes that ndjson file with human-added poster ids and sets them up in the database.\n\n**bulk:append**\n\nThis command listens on serial for PosterVote debug info, parses the data and appends to the ndjson file.\n\n1. Plug the PosterVote USB cable in and run this command.\n2. Make sure the PosterVote has a bettery in and has booted up.\n3. Hold the cable pins against the PosterVote device pads,\n   the black wire should go on the middle pad with the red wire on the `MCLR` side.\n4. Hold down the first and third PosterVote device buttons and watch the command output.\n5. A record should have been added to the ndjson file.\n\n\u003e **Device pads** — The pads are numbered 1, 2, 3, 4, 5 where MCLR is 1.\n\u003e The serial cable should be yellow=4, black=3 \u0026 red=1\n\n**bulk:insert**\n\nThis command takes the ndjson file form `bulk:append` and uses it to seed the database.\nYou need to edit the ndjson file and fill in the `\"poster\":null` bits to map each device to a poster.\nThe posters need to be created before hand through the website.\n\n## Future Work\n\n- Run database migrations on container startup\n- Give the poster pdf a name\n- Hashids the posters endpoint to stop increment attack\n- Add code coverage for IVR routes\n\n---\n\n\u003e The code on https://github.com/digitalinteraction/poster-vote-backend is a mirror of https://openlab.ncl.ac.uk/gitlab/poster-vote/node-backend\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalinteraction%2Fposter-vote-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalinteraction%2Fposter-vote-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalinteraction%2Fposter-vote-backend/lists"}