diff --git a/docs/technical-documentation/product/components/forgejo/onboarding-local-development.md b/docs/technical-documentation/product/components/forgejo/onboarding-local-development.md new file mode 100644 index 0000000..bdb2a81 --- /dev/null +++ b/docs/technical-documentation/product/components/forgejo/onboarding-local-development.md @@ -0,0 +1,281 @@ +# Forgejo + +In the following you will find + +* a lot of interestimg Forgejo links +* to to local setup and local development +* and 4 methods to set up Forgejo locally +* 3 times based only on Docker +* and once only based on Go et.al. + +## Local Setup and Development + +### Forgejo Releases + +* https://forgejo.org/releases/ + +-> the current release is 11.0 + +### method 1: docker ( - compose) with forgejo + +Method 1 is just run the or a docker image. +To be more comfortable in the parameters we can use a docker-compose file. + +run a latest forgejo with sqlite - configuration is done on first login + +* https://forgejo.org/docs/latest/admin/installation-docker/ + +#### prepare and investigate the image + +```bash +docker pull codeberg.org/forgejo/forgejo:11 + +docker inspect codeberg.org/forgejo/forgejo:11 +# check cmd and entrypoint + + # "Env": [ + # "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + # "USER=git", + # "GITEA_CUSTOM=/data/gitea" + # ], + # "Cmd": [ + # "/usr/bin/s6-svscan", + # "/etc/s6" + # ], + # "WorkingDir": "/", + # "Entrypoint": [ + # "/usr/bin/entrypoint" + # ], + +# run the image with a cli +docker run -it --entrypoint="" codeberg.org/forgejo/forgejo:11 bash + +# in the container +cat /usr/bin/entrypoint +# if [ $# -gt 0 ]; then +# exec "$@" +# else +# exec /usr/bin/s6-svscan /etc/s6 +# fi + +# check /etc/s6 + +tree /etc/s6/ +# /etc/s6/ +# ├── gitea +# │ ├── finish +# │ ├── run +# │ └── setup +# └── openssh +# ├── finish +# ├── run +# └── setup + +cat /etc/s6/gitea/run +# #!/bin/bash +# [[ -f ./setup ]] && source ./setup + +# pushd /app/gitea >/dev/null +# exec su-exec $USER /usr/local/bin/gitea web +# popd + +cat /etc/s6/gitea/setup +# #!/bin/bash + +# if [ ! -d /data/git/.ssh ]; then +# mkdir -p /data/git/.ssh +# fi + +# # Set the correct permissions on the .ssh directory and authorized_keys file, +# # or sshd will refuse to use them and lead to clone/push/pull failures. +# # It could happen when users have copied their data to a new volume and changed the file permission by accident, +# # and it would be very hard to troubleshoot unless users know how to check the logs of sshd which is started by s6. +# chmod 700 /data/git/.ssh +# if [ -f /data/git/.ssh/authorized_keys ]; then +# chmod 600 /data/git/.ssh/authorized_keys +# fi + +# if [ ! -f /data/git/.ssh/environment ]; then +# echo "GITEA_CUSTOM=$GITEA_CUSTOM" >| /data/git/.ssh/environment +# chmod 600 /data/git/.ssh/environment + +# elif ! grep -q "^GITEA_CUSTOM=$GITEA_CUSTOM$" /data/git/.ssh/environment; then +# sed -i /^GITEA_CUSTOM=/d /data/git/.ssh/environment +# echo "GITEA_CUSTOM=$GITEA_CUSTOM" >> /data/git/.ssh/environment +# fi + +# if [ ! -f ${GITEA_CUSTOM}/conf/app.ini ]; then +# mkdir -p ${GITEA_CUSTOM}/conf + +# # Set INSTALL_LOCK to true only if SECRET_KEY is not empty and +# # INSTALL_LOCK is empty +# if [ -n "$SECRET_KEY" ] && [ -z "$INSTALL_LOCK" ]; then +# INSTALL_LOCK=true +# fi + +# # Substitute the environment variables in the template +# APP_NAME=${APP_NAME:-"Forgejo: Beyond coding. We forge."} \ +# RUN_MODE=${RUN_MODE:-"prod"} \ +# DOMAIN=${DOMAIN:-"localhost"} \ +# SSH_DOMAIN=${SSH_DOMAIN:-"localhost"} \ +# HTTP_PORT=${HTTP_PORT:-"3000"} \ +# ROOT_URL=${ROOT_URL:-""} \ +# DISABLE_SSH=${DISABLE_SSH:-"false"} \ +# SSH_PORT=${SSH_PORT:-"22"} \ +# SSH_LISTEN_PORT=${SSH_LISTEN_PORT:-"${SSH_PORT}"} \ +# LFS_START_SERVER=${LFS_START_SERVER:-"false"} \ +# DB_TYPE=${DB_TYPE:-"sqlite3"} \ +# DB_HOST=${DB_HOST:-"localhost:3306"} \ +# DB_NAME=${DB_NAME:-"gitea"} \ +# DB_USER=${DB_USER:-"root"} \ +# DB_PASSWD=${DB_PASSWD:-""} \ +# INSTALL_LOCK=${INSTALL_LOCK:-"false"} \ +# DISABLE_REGISTRATION=${DISABLE_REGISTRATION:-"false"} \ +# REQUIRE_SIGNIN_VIEW=${REQUIRE_SIGNIN_VIEW:-"false"} \ +# SECRET_KEY=${SECRET_KEY:-""} \ +# envsubst < /etc/templates/app.ini > ${GITEA_CUSTOM}/conf/app.ini + +# chown ${USER}:git ${GITEA_CUSTOM}/conf/app.ini +# fi + +# # Replace app.ini settings with env variables in the form GITEA__SECTION_NAME__KEY_NAME +# environment-to-ini --config ${GITEA_CUSTOM}/conf/app.ini + +# # only chown if current owner is not already the gitea ${USER}. No recursive check to save time +# if ! [[ $(ls -ld /data/gitea | awk '{print $3}') = ${USER} ]]; then chown -R ${USER}:git /data/gitea; fi +# if ! [[ $(ls -ld /app/gitea | awk '{print $3}') = ${USER} ]]; then chown -R ${USER}:git /app/gitea; fi +# if ! [[ $(ls -ld /data/git | awk '{print $3}') = ${USER} ]]; then chown -R ${USER}:git /data/git; fi +# chmod 0755 /data/gitea /app/gitea /data/git +``` + +#### Outcome + +The container will run +* /usr/local/bin/gitea web +* with USER=git +* and DB_TYPE=${DB_TYPE:-"sqlite3" + + +#### prepare the docker compose file + +From the [link above](https://forgejo.org/docs/latest/admin/installation-docker/) copy and create a docker-compose.yml like this: + +```bash +echo $" +networks: + forgejo: + external: false + +services: + server: + image: codeberg.org/forgejo/forgejo:11 + container_name: forgejo + environment: + - USER_UID=1000 + - USER_GID=1000 + restart: always + networks: + - forgejo + volumes: + - ./forgejo:/data + - /etc/timezone:/etc/timezone:ro + - /etc/localtime:/etc/localtime:ro + ports: + - '3000:3000' + - '222:22' +" >> docker-compose.yml +``` + +### Run the container and open the WebUI + +```bash +docker compose up -d + +# open http://localhost:3000 + +### test: Check the registry + +# check registry + +docker login localhost:3000 + +docker image push localhost:3000// +``` + +### method 2: install and develop it from source + +The next real 'do development' setup method is by running the source. + + +* https://codeberg.org/forgejo/forgejo.git + +```bash +git clone https://codeberg.org/forgejo/forgejo.git + +# enter devcontainer in VSC (takes 10 mins for the first time) + +# make build + +# then run ./gitea (sic!) --help +# also see ./gitea forgejo-cli actions +``` + +### method 3: setup (a bit) declarativly - Forgejo and Forgejo Runner + +#### The kubernetes operator way + +The highly sophisticated way to do a declarative setup is already provided by the [Forgejo-Operator](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/forgejo-operator) running your desired forgejo and forgejo runner state by an operator as custom ressources. + +#### The docker-compose way + +You can also run both [Forgejo and Forgejo Runner the pure docker way.](https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/stephan.lo/stl-edp/src/branch/development/09-forgejo) + +```bash +git clone https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/stephan.lo/stl-edp.git + +git checkout development + +cd 09-forgejo + +# spin up +# ... first check and understand the content of the script ! +./spin-up.sh + +# destroy +./teardown.sh +``` + +Also have a look into the linsk provided in the README, especially https://codeberg.org/forgejo-contrib/delightful-forgejo + +### method 4: 'setup forgejo' (with runner) + +Really funny and promisingly looking high-end-community-development stuff is this: + +* https://code.forgejo.org/actions/setup-forgejo + + +```bash +git clone https://code.forgejo.org/actions/setup-forgejo.git +``` + + +## References + +### Meta + +* https://codeberg.org/forgejo + +### Forgejo Development + +* https://forgejo.org/docs/v1.21/developer/architecture/ +* https://forgejo.org/docs/v1.21/developer/customization/ + +### UI + +* https://codeberg.org/forgejo/discussions/issues/338 + +### Some nice Setup references + +* https://brainsteam.co.uk/2024/03/17/moving-from-gitea-to-forgejo-including-actions-with-docker-compose/ +* https://code.forgejo.org/forgejo/runner +* https://linus.dev/posts/setting-up-a-self-hosted-forgejo-actions-runner-with-docker-compose/