diff --git a/.docker/.env b/.docker/.env new file mode 100644 index 000000000..b5237c4c6 --- /dev/null +++ b/.docker/.env @@ -0,0 +1,22 @@ +NODE_VERSION="19.4" + +BIND_ADDRESS_HOST=localhost +BIND_ADDRESS_PORT=8080 + +# Env variables must have the prefix VITE_ for Vite to include them. +# More information about env variables with Vite can be found here: https://vitejs.dev/guide/env-and-mode.html +VITE_BASE_API_URL=http://localhost:8080 +VITE_NEXTCLOUD_URI=https://cloud.permaplant.net +# OAuth2 (other URLs will be fetched from this URL) +AUTH_DISCOVERY_URI=https://auth.permaplant.net/realms/PermaplanT/.well-known/openid-configuration +AUTH_CLIENT_ID=localhost + +# DB +POSTGRES_USER=permaplant +POSTGRES_DB=permaplant +POSTGRES_PASSWORD=permaplant +PGPASSWORD=permaplant +DATABASE_URL=postgres://permaplant:permaplant@localhost/permaplant + +PGADMIN_DEFAULT_EMAIL=name@example.com +PGADMIN_DEFAULT_PASSWORD=permaplant diff --git a/.docker/.env.db b/.docker/.env.db new file mode 100644 index 000000000..e8269af44 --- /dev/null +++ b/.docker/.env.db @@ -0,0 +1,8 @@ +POSTGRES_USER=permaplant +POSTGRES_DB=permaplant +POSTGRES_PASSWORD=permaplant +PGPASSWORD=permaplant +DATABASE_URL=postgres://permaplant:permaplant@localhost/permaplant + +PGADMIN_DEFAULT_EMAIL=name@example.com +PGADMIN_DEFAULT_PASSWORD=permaplant diff --git a/.docker/Dockerfile.pg b/.docker/Dockerfile.pg new file mode 100644 index 000000000..375faf461 --- /dev/null +++ b/.docker/Dockerfile.pg @@ -0,0 +1,5 @@ +# This Dockerfile is used inside the docker-compose.yml as development environment +FROM dpage/pgadmin4:7.3 + +COPY ./servers.json ./servers.json +COPY ./pgpass ../pgpass diff --git a/.docker/docker-compose.yml b/.docker/docker-compose.yml new file mode 100644 index 000000000..96f590131 --- /dev/null +++ b/.docker/docker-compose.yml @@ -0,0 +1,30 @@ +version: "3.8" + +services: + db: + image: postgis/postgis:13-3.1 + restart: unless-stopped + volumes: + - postgis-data-dev:/var/lib/postgresql/data + env_file: + - .env + ports: + - "5432:5432" + + pgadmin: + build: + context: . + dockerfile: Dockerfile.pg + restart: unless-stopped + volumes: + - pgadmin-data-dev:/var/lib/pgadmin + env_file: + - .env.db + ports: + - "5050:80" + +volumes: + pgadmin-data-dev: + external: false + postgis-data-dev: + external: false diff --git a/.docker/pgpass b/.docker/pgpass new file mode 100644 index 000000000..fa4b33555 --- /dev/null +++ b/.docker/pgpass @@ -0,0 +1 @@ +db:5432:permaplant:permaplant:permaplant diff --git a/.docker/servers.json b/.docker/servers.json new file mode 100644 index 000000000..7594aea76 --- /dev/null +++ b/.docker/servers.json @@ -0,0 +1,14 @@ +{ + "Servers": { + "1": { + "Name": "permaplant", + "Group": "Servers", + "Host": "db", + "Port": 5432, + "MaintenanceDB": "postgres", + "Username": "permaplant", + "PassFile": "/pgpass", + "SSLMode": "prefer" + } + } +} diff --git a/Makefile b/Makefile index 532ea631f..15ab61a74 100644 --- a/Makefile +++ b/Makefile @@ -89,9 +89,8 @@ doc-frontend: install-types install-frontend ## Frontend src doc # Install - .PHONY: install -install: install-pre-commit install-backend install-mdbook install-frontend install-e2e install-types ## Install ALL dependencies within the source repo +install: install-pre-commit install-backend install-mdbook install-frontend install-e2e install-types ## Install ALL dependencies within the source repo @echo "Installation completed." .PHONY: install-types diff --git a/doc/changelog.md b/doc/changelog.md index fabb8de44..8c04fe71a 100644 --- a/doc/changelog.md +++ b/doc/changelog.md @@ -8,7 +8,7 @@ Syntax: `- short text describing the change _(Your Name)_` ## UNRELEASED -- _()_ +- Update Dev-Setup Documentation & Add docker folder _(Jannis, Lukas)_ - _()_ - _()_ - _()_ diff --git a/doc/development/01docker+local.md b/doc/development/01docker+local.md new file mode 100644 index 000000000..5feb0aef8 --- /dev/null +++ b/doc/development/01docker+local.md @@ -0,0 +1,24 @@ +# Docker + local + +Run the database in Docker and the frontend and backend locally. + +## Install Docker + +[Install Docker](https://docs.docker.com/engine/install/) for your host OS. + +## Installing Node + Npm + +Make sure node, in the version as required for PermaplanT, is installed, you may use to easily install multiple versions of node [nvm](https://github.com/nvm-sh/nvm), use apt or [download node directly](https://nodejs.org/en/download). + +## Install Rust + +Follow the steps to [install Rust using rustup](https://www.rust-lang.org/tools/install). + +## Run the database + +This runs the Postgis database and PgAdmin. + +```bash +cd docker +docker compose up -d +``` diff --git a/doc/development/02devcontainer.md b/doc/development/02devcontainer.md new file mode 100644 index 000000000..3b0df5cfa --- /dev/null +++ b/doc/development/02devcontainer.md @@ -0,0 +1,30 @@ +# Devcontainer + +We are also supporting a containerized setup(docker/podman). For more information checkout the README inside [.devcontainer](https://github.com/ElektraInitiative/PermaplanT/blob/master/.devcontainer/README.md). + +## Background + +(Devcontainer)[https://code.visualstudio.com/docs/devcontainers/containers] allows you to +develop using VSCode, without installing Node and Rust, you only need Docker and the +Dockercontainer extention. + +## Install the extention + +[Devcontainer](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extention and choose +`Dev Containers: Reopen in Container` in the VSCode command palette. The devcontainer includes a `PgAdmin` container on port `5050`, +see the `.devcontainer` directory. + +Within the devcontainer install all dependencies with + +```bash +make install +``` + +## Git user + +Globally set git credentials are not available in the devcontainer, set them loaclly. + +```bash +git config user.name "Your name" +git config user.email "Your email" +``` diff --git a/doc/development/03local.md b/doc/development/03local.md new file mode 100644 index 000000000..b542b294a --- /dev/null +++ b/doc/development/03local.md @@ -0,0 +1,19 @@ +# Local + +Run everything locally on your machine. + +## Installing Node + Npm + +Make sure node, in the version as required for PermaplanT, is installed, you may use to easily install multiple versions of node [nvm](https://github.com/nvm-sh/nvm), use apt or [download node directly](https://nodejs.org/en/download). + +## Install Rust + +Follow the steps to [install Rust using rustup](https://www.rust-lang.org/tools/install). + +## Install Postgis + +Install postgres, for instance on Ubuntu: + +```bash +apt-get install libpq-dev postgresql-client +``` diff --git a/doc/development_setup.md b/doc/development_setup.md index ad152c785..f4a1f1701 100644 --- a/doc/development_setup.md +++ b/doc/development_setup.md @@ -3,22 +3,36 @@ ## Prerequisites If you want to develop on the backend, make sure you have enough RAM. -When performing cargo build, we have experienced (on wsl) a usage of ~12GB. - -- Python -- Rust -- Javascript - - nvm - - node +When performing cargo build, we have experienced a usage of ~12GB. ## Operating Systems -- Windows 11 -- macOS 13.1 (Unix) +- Ubuntu or another Ubuntu/Debian-based Linux system +- Ubuntu in [WSL](https://learn.microsoft.com/de-de/windows/wsl/install) on Windows + +## Ways to develop PermaplanT + +Right now we have three different ways to develop PermaplanT: + +### Docker services + local development + +Run the database and other services in Docker containers but run backend and frontend locally. +[Read more](development/01docker+local.md) + +### Dev container + +Run everything within the VSCode devcontainer. +[Read more](development/02devcontainer.md) + +### Local setup + +Run everything locally, including the database setup. +[Read more](development/03local.md) ## IDE - [Visual Studio Code](https://code.visualstudio.com/) for both Frontend and Backend +- [IntelliJ IDEA](https://www.jetbrains.com/idea/?var=1) for both Frontend and Backend ## Visual Studio Code Extensions @@ -39,57 +53,6 @@ Rust formatting can be achieved by adding the following to settings.json in VSCo } ``` -## Package Managers - -- Frontend [npm](https://www.npmjs.com/) -- Backend [cargo](https://crates.io/) - -### Installing Node + Npm - -If you are using unix, macOS, and windows WSL, consider using [nvm](https://github.com/nvm-sh/nvm) -to manage your node environment: - -```bash -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash -nvm install 20 -nvm use 20 -``` - -Or if you use the default macOS starting with Catalina shell `zsh`, try: - -```zsh -sh -c "$(curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh)" -``` - -### Installing Rust + Cargo - -If you’re using Linux or macOS, open a terminal and enter the following command: - -```bash -$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh -``` - -This installs rust and cargo automatically on your machine. -If you get linker errors, proceed by installing a C Compiler, which will typically include a linker. - -To install our specific version of Rust, just run the following command: - -```bash -rustup install 1.74 -``` - -On Windows, go to https://www.rust-lang.org/tools/install and follow the instructions for installing Rust. -At some point in the installation, you’ll receive a message explaining that you’ll also need the MSVC build tools for Visual Studio 2013 or later. - -To acquire the build tools, you’ll need to install Visual Studio 2022. When asked which workloads to install, include: - -- Desktop Development with C++ -- The Windows 10 or 11 SDK -- The English language pack component, along with any other language pack of your choosing - -In case you don't prefer any of the previously mentioned installations methods, click -[here](https://forge.rust-lang.org/infra/other-installation-methods.html) for alternatives. - ## Browsers - Chrome 108.0.5359 @@ -103,10 +66,14 @@ If you want to install all necessary dependencies for development run following make install ``` -## Containers - -We are also supporting a containerized setup(docker/podman). For more information checkout the README inside [.devcontainer](https://github.com/ElektraInitiative/PermaplanT/blob/master/.devcontainer/README.md). - ## Github Codespaces PermaplanT supports Github codespaces. If you are interested in developing inside Github Codespaces you can learn more about [here](https://docs.github.com/de/codespaces). + +## Backend Setup + +[Setup for Backend](backend/01setup.md) + +## Frontend Setup + +[Readme in Frontend](../frontend/README.md)