Pictogrammers.com

Development

Requirements

• Node.js v18+
• Docker

Instructions

1. Clone this repository.
2. Generate your development certificates.
   • On Mac, run npm run certs:mac. You need Homebrew to be installed.
   • On Windows, run npm run certs:win. You need Chocolatey to be installed.
   • On any other platform, see Generating Dev Certs.
   • Once your certs are generated, you do not need to run this command again unless you delete the certs or they expire.
3. Run npm i.
4. Run npm run dev to start the dev servers.
   • Access the dev site at https://dev.pictogrammers.com.
   • Access the dev API at https://dev-api.pictogrammers.com.
   • The dev MySQL instance will come up at http://localhost:3306.

The site and API will hot-reload as you make changes.

See https://pictogrammers.com/docs/contribute/website/ for more details about contributing to the site.

Generating Dev Certs

If you are not using Mac or Windows, you will need to follow the instructions on the mkcert GitHub page to install the version for your platform.

You need to generate certs for the following two domains:

• dev.pictogrammers.com
• dev-api.pictogrammers.com

Place these certifications in the .dev/certs directory. Then start the application.

Env variables

GitHub API Access Token (REQUIRED)

As part of the site's build process, information is pulled from GitHub about our contributors. This data is required for the site to build.

1. Create a classic GitHub personal access token.
   • Required permissions: public_repo, read:org, read:user, user:email
2. Create a .env file in the root of the repository.
3. Add API_KEY_GITHUB to the .env file with your token.
4. Restart the dev server.

GitHub OAuth Client & Secret (Optional)

To test and debug any part of the site behind authentication, you will need to create a GitHub OAuth application and provide the Client ID and Secret in the environment file.

This is not required to work on public facing areas of the site. You will be unable to log in/out or access areas of the site behind authentication.

1. Create a GitHub OAuth App.
2. Use https://dev-api.pictogrammers.com/auth/github/callback as the "Authorization callback URL".
3. Create a .env file in the root of the repository.
4. Copy and paste your client ID and secret into the env file.

   GITHUB_CLIENT_ID={YOUR_CLIENT_ID}
   GITHUB_CLIENT_SECRET={YOUR_CLIENT_SECRET}

5. Restart the dev server.

Code Quality

Before opening a PR with your changes, be sure to run npm run lint and correct any linting errors. These jobs will also run on the PR, informing you of failures that will need to be addressed before your PR can be merged.

Building

You shouldn't need to build locally. This information is provided for advanced troubleshooting cases.

1. Run npm build to build the site and API.
2. The built assets will be located in the following folders:
   • Client: /client/dist
   • API: /api/dist

Legal

© Copyright 2023 Pictogrammers.