# Getting Started This [GitHub organization](https://github.com/island-is) is the center of development for digital government services on `island.is`. It is managed by the [Digital Iceland](https://stafraent.island.is/) department inside the [Ministry of Finance and Economic Affairs](https://www.government.is/ministries/ministry-of-finance-and-economic-affairs/). These solutions are [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) and open to contributions, but most development will be performed by teams that win tenders to develop new functionality for Digital Iceland. The repository is a [monorepo](/technical-overview/monorepo.md) that has multiple apps (something that can be built and run) and libraries (which other apps and libraries can depend on). All custom-written services are also stored there. ## GitBook The apps and libraries documentation and our handbook are hosted on [GitBook](https://www.gitbook.com) and is publicly available at [docs.devland.is](https://docs.devland.is). ## Storybook The Ísland.is design system is developed and showcased using [Storybook](https://storybook.js.org) and is publicly available at [ui.devland.is](https://ui.devland.is). ## Reading material To get more technical information about the project please make sure to read this [overview](/technical-overview/technical-overview.md). ## External contributors If you want to contribute to the repository, please make sure to follow [this guide](/development/external-contribute.md). ## Prerequisites * You have Node and Yarn installed as outlined in the `engines` section in the repository's [`package.json`](https://github.com/island-is/island.is/blob/main/package.json#L5) * You have [Docker](https://docs.docker.com/desktop/) installed. * You have [direnv](https://direnv.net/) installed. * You have [Java](https://www.java.com/en/download/manual.jsp) `>= 1.8` installed (for schema generation). {% hint style="info" %} If you are running on Windows we recommend using [Docker and WSL2](https://docs.docker.com/desktop/windows/wsl/) {% endhint %} ### For fetching secrets * You have [AWS command line tools v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed. * `brew install awscli` * You have [jq](https://stedolan.github.io/jq/) installed. * `brew install jq` ## Usage There are many projects that can be built and run. To list projects that can be built the following command can be used ```bash yarn nx show projects --with-target build ``` See further useage of the Nx show command in their [docs](https://nx.dev/nx-api/nx/documents/show). ### Fresh start/changing branches Run on whenever you check out a branch: ```bash yarn install yarn infra yarn codegen ``` When you clone the repo for the first time, and whenever you change branches, you need to update your dependencies to match your current branch using `yarn install`. In addition, schemas change frequently, so you will also need to update the generated schemas and clients using `yarn codegen`. ### Development server For a dev server: ```bash yarn start ``` The app will automatically reload if you change any of the source files. ### Build To build the project: ```bash yarn build ``` The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build. ### Formatting your code You need to format all files to follow Nx code conventions. To do so run: ```bash yarn nx format:write ``` ### Running lint checks We have many lint rules to help having a unify code all over the project. To execute the linting: ```bash yarn lint ``` > Running lint locally is slow and fill up heap memory. This is related to Typescript compilation and Nx lint builder being slow. As a result you might get a `JavaScript heap out of memory`. Nx is working on fixing this for an upcoming update. In the meantime you can do `NODE_OPTIONS=“--max-old-space-size=4096” yarn lint ` to raise the memory limit. ### Running unit tests To execute the unit tests via [Jest](https://jestjs.io): ```bash yarn test ``` To execute the unit tests affected by a change: ```bash yarn affected:test ``` ### Running end-to-end tests See our technical documentation on our [system e2e setup](https://github.com/island-is/island.is/tree/main/apps/system-e2e). ### Schemas If your project is generating schemas files from an OpenAPI, Codegen or is an API, check out [this documentation](/development/codegen.md). ### Understand your workspace To see a diagram of the dependencies of your projects: ```bash yarn nx dep-graph ``` ### AWS Secrets A dedicated documentation about fetching shared development secrets or creating new secrets, using AWS secrets is available [here](/development/aws-secrets.md). ### Running proxy against development service If you have AWS access to our development account, you can connect to development databases and services using a proxy. We've set up a proxy and connection helpers for our development Postgres, Elastic Search, Redis and X-Road Security Server. To do so, you can run for example: ```bash ./scripts/run-db-proxy.sh ``` It will try to get your AWS credentials from your environment variables and from your `~/.aws/credentials` file. You can find more instructions [here](/development/aws-secrets.md#using-aws-session). {% hint style="info" %} If you want to run your app against one of this service (e.g. `db`), you may need to edit your app environment or sequelize config to pass the proxy credentials. {% endhint %} {% hint style="warning" %} The following services will run on the associated ports: `db:5432`, `es:9200`, `redis:6379`, `xroad:80`. If you have docker running on theses ports or any others services you will need to stop them in order to run the proxies. {% endhint %} ### Environment variables with static websites To be able to access environment variables in purely static projects, you need to do the following: 1. In the index.html file, add ``. 2. Use the `getStaticEnv` function from the `@island.is/shared/utils` library to fetch your environment variables. 3. Prefix your environment variables with `SI_PUBLIC_`, for example `SI_PUBLIC_MY_VARIABLE`. NOTE: This is only to get environment variables when running in kubernetes, not for when running locally. So you should only use `getStaticEnv` in your `environment.prod.ts` file. What happens behind the scenes is that static projects have a bash script that runs when the docker container starts up. This script searches for references of `SI_PUBLIC_*` in the code and tries to find a match in the environment. It then puts all the matches inside the index.html which is then served to the client. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.devland.is/development/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.