diff --git a/Installation.md b/Installation.md new file mode 100644 index 0000000..232f1fc --- /dev/null +++ b/Installation.md @@ -0,0 +1,302 @@ +# Prerequisites + +Clearing houz (clrghouz) is current configured to run on Linux systems under docker. The docker host only needs to have docker installed, and networking configured. + +If you have a single IPv4 address, your docker host will receive connections (on appropriate web and FTN ports), and proxy those connections through to the docker containers that respond to those ports. + +If you have IPv6, then the docker containers can be configured with a public IPv6 address and receive connections directly. + +## Installing Docker + +It is recommended to install docker from docker directly (as often linux distribution implementations are often behind the current release). To do so, it can be achieved with a simple command: + +`curl -sSL https://get.docker.com | sudo sh` + +To test that installation was successful, run `sudo docker info` and you should see something similar to below: + +```plaintext +Client: Docker Engine - Community + Version: 24.0.6 + Context: default + Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc.) + Version: v0.11.2 + Path: /usr/libexec/docker/cli-plugins/docker-buildx + compose: Docker Compose (Docker Inc.) + Version: v2.21.0 + Path: /usr/libexec/docker/cli-plugins/docker-compose + +Server: + Containers: 4 + Running: 2 + Paused: 0 + Stopped: 2 +... + Docker Root Dir: /var/lib/docker + Debug Mode: false + Experimental: false + Insecure Registries: + 127.0.0.0/8 + Live Restore Enabled: false +``` + +## Running docker as a user + +Normally docker commands can only be run as the `root` user. However, to run docker commands with your (non-root) user id - add your user to the `docker` group. + +`sudo usermod -aG docker [your_user_id]` + +will do it. You'll need to log off and log on again for it to be effective. + +You can confirm with `id` + +``` +[deon@c-8-1 php]$ id fred +uid=500(fred) gid=500(admin) groups=500(admin),10(wheel),27(sudo),498(docker) +``` + +(In the above example, you can see `fred` is a member of GID: 498 `docker`.) + +## Storage directory + +You will want all your data to persist between container restarts. Create a directory to store all the container directory - something like `/srv/docker` (or something you prefer). + +## Storage space + +Make sure your docker container directory (`/srv/docker`) and `/var/lib/docker` has sufficient space. + +If your linux doesnt use mount points, and all your space is mounted under `/`, then you should be OK. But if you do have mount points, then you'll need to have lots of space reserved for those directories. + +## Create a directory for Clearing houz + +In your storage directory (`/srv/docker`) create a directory to store Clearing houz files (eg:`/srv/docker/clrghouz`). Everything from here on will assume you are working from this directory. + +### docker compose + +To make restarting containers easier, here is a docker compose file that you can use - this will go in your Clearing houz directory. Make adjustments as appropriate. + +```plaintext +version: "3.5" + +services: + web: + image: registry.dege.au/bbs/clrghouz + #cap_add: + # SYS_ADMIN + # NET_ADMIN + # NET_RAW + depends_on: + - postgres + deploy: + resources: + limits: + memory: 512M + #devices: + # /dev/net/tun + environment: + APP_KEY: [APP_KEY] + APP_TIMEZONE: Australia/Melbourne + APP_URL: https://clrghouz.test.dege.au/ + AWS_ACCESS_KEY_ID: "[MINIO_ACCESS_KEY]" + AWS_SECRET_ACCESS_KEY: "[MINIO_SECRET_KEY]" + AWS_ENDPOINT: http://minio:9000/ + AWS_BUCKET: clrghouz + DB_PASSWORD: "[DB_PASSWORD]" + FIDO_PACKET_KEEP: "true" + FIDO_HAPROXY: "false" + LOG_LEVEL: info + MAIL_FROM_ADDRESS: your@email.address + MAIL_FROM_NAME: "YOUR NAME" + MEMCACHED_START: "TRUE" + #ZEROTIER_START: "false" + networks: + default: + public: + ipv6_address: [IPv6_PREFIX]:0d0c:e02::2 + aliases: + - clrghouz + hostname: clrghouz.test.dege.au + ports: + - 53:53/udp + #- 80:80 + #- 24554:24554 + #- 60179:60179 + sysctls: + - "net.ipv6.conf.all.disable_ipv6=0" + volumes: + - /srv/docker/clrghouz/app/cache:/var/www/html/storage/framework/cache/data + - /srv/docker/clrghouz/app/sessions:/var/www/html/storage/framework/sessions + - /srv/docker/clrghouz/app/logs:/var/www/html/storage/logs + - /srv/docker/clrghouz/app/data:/var/www/html/data + - /srv/docker/clrghouz/app/fido:/var/www/html/storage/app/fido + # /srv/docker/clrghouz/zerotier:/var/lib/zerotier-one + + queue: + image: registry.dege.au/bbs/clrghouz + #cap_add: + # SYS_ADMIN + # NET_ADMIN + depends_on: + - postgres + deploy: + replicas: 1 + resources: + limits: + memory: 512M + #devices: + # /dev/net/tun + environment: + APP_KEY: [APP_KEY] + APP_TIMEZONE: Australia/Melbourne + APP_URL: https://clrghouz.test.dege.au/ + AWS_ACCESS_KEY_ID: "[MINIO_ACCESS_KEY]" + AWS_SECRET_ACCESS_KEY: "[MINIO_SECRET_KEY]" + AWS_ENDPOINT: http://minio:9000/ + AWS_BUCKET: clrghouz + CACHE_DRIVER: file + CONTAINER_ROLE: queue + DB_PASSWORD: "[DB_PASSWORD]" + LOG_LEVEL: info + MAIL_FROM_ADDRESS: your@email.address + MAIL_FROM_NAME: "YOUR NAME" + WORK_QUEUES: default,poll,tic + WORK_TIMEOUT: 900 + #ZEROTIER_START: "false" + networks: + default: + public: + ipv6_address: [IPv6_PREFIX]:0d0c:e02::3 + sysctls: + - "net.ipv6.conf.all.disable_ipv6=0" + volumes: + - /srv/docker/clrghouz/app/logs:/var/www/html/storage/logs + - /srv/docker/clrghouz/app/fido:/var/www/html/storage/app/fido + # /srv/docker/clrghouz/zerotier.queue:/var/lib/zerotier-one + + schedule: + image: registry.dege.au/bbs/clrghouz + deploy: + replicas: 1 + resources: + limits: + memory: 128M + depends_on: + - postgres + environment: + APP_KEY: [APP_KEY] + APP_TIMEZONE: Australia/Melbourne + APP_URL: https://clrghouz.test.dege.au/ + CACHE_DRIVER: file + CONTAINER_ROLE: scheduler + DB_PASSWORD: "[DB_PASSWORD]" + networks: + default: + volumes: + - /srv/docker/clrghouz/app/logs:/var/www/html/storage/logs + - /srv/docker/clrghouz/app/fido:/var/www/html/storage/app/fido + + postgres: + image: postgres:15-alpine + deploy: + resources: + limits: + memory: 512M + environment: + POSTGRES_DB: clrghouz + POSTGRES_USER: clrghouz + POSTGRES_PASSWORD: "[DB_PASSWORD]" + networks: + default: + #labels: + # cron.container.daily: "root#pg_dumpall -U clrghouz#S3_BUCKET=restic.docker restic -q --no-cache backup --stdin --stdin-filename docker-clrghouz-database" + # backup.stack.daily: "/srv/docker/clrghouz" + shm_size: 1g + volumes: + - /srv/docker/clrghouz/postgres:/var/lib/postgresql/data + + minio: + image: tobi312/minio + command: ["server", "--console-address", ":9001", "/data"] + deploy: + resources: + limits: + memory: 128M + healthcheck: + test: [ "CMD", "curl", "--fail", "http://localhost:9000/minio/health/live" ] + interval: 60s + timeout: 10s + retries: 3 + networks: + default: + ports: + - 9001:9001 # Console + volumes: + - /srv/docker/clrghouz/minio:/data + + haproxy: + image: haproxy + command: -f /usr/local/etc/haproxy/config + #cap_add: + #- NET_ADMIN + deploy: + resources: + limits: + memory: 128M + hostname: hap-1-1.test.dege.au + networks: + default: + public: + ipv6_address: [IPv6_PREFIX]:0d0c:e02::f + ports: + - "24553:24553" + - "24554:24554" + - "60179:60179" + # "53:53/udp" + - "80:80" + - "443:443" + volumes: + - /srv/docker/clrghouz/haproxy:/usr/local/etc/haproxy/config + - /srv/docker/clrghouz/nginx/ssl/:/usr/local/etc/haproxy/ssl + +networks: + public: + enable_ipv6: true + driver: bridge + driver_opts: + com.docker.network.enable_ipv6: "true" + ipam: + driver: default + config: + - subnet: [IPv6_PREFIX]:0d0c:e02::/96 + gateway: [IPv6_PREFIX]:0d0c:e02::1 +``` + +_NOTES:_ + +* This docker compose file should be called `docker-compose.yml` +* You'll defined the `[APP_KEY]` below +* Update the `[IPv6_PREFIX]` as appropriate for your setup. This assumes you have your IPv6 setup, and you have configured your router to route this prefix to this host running clrghouz. +* Create a suitable `[DB_PASSWORD]` and update your docker-compose file. +* We'll define `[MINIO_ACCESS_KEY]` and `[MINIO_SECRET_KEY]` later - and you'll update your docker-compose file with those details. +* If you dont want to use haproxy, then you can comment/delete out this section in the docker-compose file. You'll also need to uncomment the post definitions in the _web:_ section. +* If you dont want to use nginx, or already have nginx as a front end to your web hosts elsewhere, then you can comment/delete it from your docker-compose file. (You'll configure your existing nginx to terminate SSL and/or proxy to the _web:_ container on port 80.) + +### Make necessary directories + +```plaintext +# mkdir app app/cache app/data app/fido app/logs app/sessions haproxy minio postgres nginx +# sudo chown -R 82:82 app/ +``` + +### Create the app encryption key + +```plaintext +# docker run --rm -e CONTAINER_ROLE=none -e APP_TIMEZONE=UTC registry.dege.au/bbs/clrghouz ./artisan key:generate --show + +* Starting NGINX... +? NO container role "none", AND/OR no laravel install, just starting php-fpm +base64:iT+8vM9p0X8oupGPKF+/ZqAxqyIQY5dWd72TaAlfcdY= <--- WHAT IS HERE IS YOUR KEY +``` + +And update the docker-compose file and replace `[APP_KEY]` with this key. \ No newline at end of file