Unified GraphQL API for Serlo.

You need:

• Node.js from .tool-versions installed on your system. Enable yarn via running corepack enable.
  • You may use asdf for the installation.
• Docker

Now follow the upcoming instructions.

# Clone the project:
$ git clone https://github.com/serlo/api.serlo.org.git
$ cd api.serlo.org

Run yarn to install the dependencies of all packages.

Make sure Docker is running and then run yarn start to start Redis.

If in the /etc/hosts file of your host you have the ::1 (IPv6) mapped to localhost, you will additionally need to set: --dns-result-order=ipv4first in the NODE_OPTIONS environment variable:

export NODE_OPTIONS=--dns-result-order=ipv4first

By default, while developing, the caching won't work. If you want to have caching, change the value CACHE_TYPE in .env to any other value besides 'empty'.
To check the cache locally, run yarn cache:cli.

Some other useful commands:
redis:empty removes the whole cache redis:list lists all cached keys

• yarn test runs the unit tests (requires yarn start:containers beforehand)
• yarn pacts runs the contract tests (requires yarn start:containers beforehand)
• yarn check:all runs all checks (like the linter and tests) to check whether your codebase is ready to be merged into main

You can pass the name of your test as an argument. For example to only run the tests of the metadata.

yarn test -- metadata

After yarn start, you can open the GraphQL playground via http://localhost:3000/___graphql. Note that most queries will need a running serlo/serlo.org-database-layer dev environment.

If you need to run requests authenticated/authorized, use yarn auth to be authenticated as user with id 1 or yarn auth <id> to choose a specific user.

Happy coding!

Interrupt the yarn start command to stop the dev server and run yarn down to remove all containers.

You can use git hooks to automatically check the whole codebase before you push to the server. To configure it, run the following commands in the root directory:

echo "yarn check:all --no-uncommitted-changes" > .git/hooks/pre-push
chmod +x .git/hooks/pre-push

With git push --no-verify you can bypass the automatic checks.

• yarn build:server builds the server (only needed for deployment)
• yarn format formats all source code
• yarn lint lints all source code
• yarn license updates license headers in source files
• yarn pacts runs the contract tests
• yarn test runs the unit tests
• yarn codegen generates TypeScript types from GraphQL schema
• yarn start spins up the development environment

Run yarn migrate:new to create a new file with the migration timestamp.

You can copy and paste one of the existing migrations as a template for the new one.

Do yarn migrate:run <path to your migration> to test your code. You may want to run mysql:delete-last-migration or even yarn mysql:rollback every now and then.

To create a new image, just change the version at packages/db-migrations/package.json. If the migration isn't supposed to be used by other developers nor to be run in CI, create version with prerelease (v.g. 2.0.2-staging.0).

After deploying the image in production, create a new test dump. Follow the steps at serlo/serlo-mysql-database.

Via filtering PRs by base:production you can access the changelog of production.

We use Ory Kratos for our user management. Usually you won't need it, but if you do, run first:

yarn start:kratos

In the folder ./kratos you find all important configuration files. Emails sent by Kratos are going to be found at http://localhost:4436.

For more info about it see its documentation.

First of all add nbp and vidis as host
sudo bash -c "echo '127.0.0.1 nbp'" >> /etc/hosts sudo bash -c "echo '127.0.0.1 vidis'" >> /etc/hosts

why do I need it? Kratos makes a request to the url of the oauth2 provider, but since it is running inside a container, it cannot easily use the host port. These DNSs are discoverable for the kratos container, so the host can also use it.

Run yarn start:sso.
Make sure you already run yarn start:kratos before.

Keycloak UI is available on nbp:11111 and vidis:11112.
Username: admin, pw: admin.
There you have to configure Serlo as a client.

Client -> Create Client

id: serlo
home and root url: http://localhost:3000
redirect uri: http://localhost:4433/self-service/methods/oidc/callback/nbp
// OR redirect uri: http://localhost:4433/self-service/methods/oidc/callback/vidis

Get the credentials and go to kratos/config.yml:

selfservice:
  methods:
    oidc:
      enabled: true
      config:
        providers:
          - id: nbp # or vidis
            provider: generic
            client_id: serlo
            client_secret: <put secret here>

Run the local frontend (not forgetting to change environment in its .env to local) to test.

Hint: you may want to create some users in Keycloak in order to test.

Kratos has to be rebuilt every time you change an email template. Use the following workflow:

1. Edit templates. See at kratos/config.yml where they are.
2. Run yarn kratos:rebuild
3. Test the verification or the recovery email at localhost:4436. Repeat the process.