Docker Compose install guide

.config/example-docker.yml

@@ -0,0 +1,266 @@
+#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Iceshrimp configuration
+#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+# After starting your server, please don't change the URL! Doing so will break federation.
+
+#   ┌─────┐
+#───┘ URL └─────────────────────────────────────────────────────
+
+# Final accessible URL seen by a user.
+url: https://example.org/
+
+# (Optional - ADVANCED) Domain used for account handles.
+# Only uncomment this if you want to for example have the URL be ice.example.org
+# and the handles to be example.org
+# accountDomain: example.org
+
+#   ┌───────────────────────┐
+#───┘ Port and TLS settings └───────────────────────────────────
+
+#
+# Iceshrimp requires a reverse proxy to support HTTPS connections.
+#
+#                 +----- https://example.com/ ------------+
+#   +------+      |+-------------+      +----------------+|
+#   | User | ---> || Proxy (443) | ---> | Iceshrimp (3000) ||
+#   +------+      |+-------------+      +----------------+|
+#                 +---------------------------------------+
+#
+#   You need to set up a reverse proxy. (e.g. nginx, caddy)
+#   An encrypted connection with HTTPS is highly recommended
+#   because tokens may be transferred in GET requests.
+
+# The port that your Iceshrimp server should listen on.
+port: 3000
+
+#   ┌──────────────────────────┐
+#───┘ PostgreSQL configuration └────────────────────────────────
+
+db:
+  host: db
+  port: 5432
+  #ssl: false
+  # Database name
+  db: iceshrimp
+
+  # Auth
+  user: example-iceshrimp-user
+  pass: example-iceshrimp-pass
+
+  # Whether disable Caching queries
+  #disableCache: true
+
+  # Extra Connection options
+  #extra:
+  #  ssl:
+  #   host: localhost
+  #   rejectUnauthorized: false
+
+#   ┌─────────────────────┐
+#───┘ Redis configuration └─────────────────────────────────────
+
+redis:
+  host: redis
+  port: 6379
+  #tls:
+  #  host: localhost
+  #  rejectUnauthorized: false
+  #family: 0  # 0=Both, 4=IPv4, 6=IPv6
+  #pass: example-pass
+  #prefix: example-prefix
+  #db: 1
+  #user: default
+
+#   ┌────────────────────────────┐
+#───┘ Cache server configuration └──────────────────────────────
+
+# A Redis-compatible server (DragonflyDB, Keydb, Redis) for caching
+# If left blank, it will use the Redis server from above
+# Possible values for host: dragonflydb, keydb, redis_cache
+
+#cacheServer:
+  #host: 
+  #port: 6379
+  ##family: 0  # 0=Both, 4=IPv4, 6=IPv6
+  ##pass: example-pass
+  ##prefix: example-prefix
+  ##db: 1
+
+# Please configure either MeiliSearch *or* Sonic.
+# If both MeiliSearch and Sonic configurations are present, MeiliSearch will take precedence.
+
+#   ┌───────────────────────────┐
+#───┘ MeiliSearch configuration └───────────────────────────────
+#meilisearch:
+#  host: meilisearch
+#  port: 7700
+#  ssl: false
+#  apiKey:
+
+#   ┌─────────────────────┐
+#───┘ Sonic configuration └─────────────────────────────────────
+
+#sonic:
+#  host: sonic
+#  port: 1491
+#  auth: SecretPassword
+#  collection: notes
+#  bucket: default
+
+
+#   ┌───────────────┐
+#───┘ ID generation └───────────────────────────────────────────
+
+# No need to uncomment in most cases, but you may want to change
+# these settings if you plan to run a large and/or distributed server.
+
+# cuid:
+#   # Min 16, Max 24
+#   length: 16
+#
+#   # Set this to a unique string across workers (e.g., machine's hostname)
+#   # if your workers are running in multiple hosts.
+#   fingerprint: my-fingerprint
+
+
+#   ┌─────────────────────┐
+#───┘ Other configuration └─────────────────────────────────────
+
+# Maximum length of a post (default 3000, max 100000)
+#maxNoteLength: 3000
+
+# Maximum length of an image caption (default 1500, max 8192)
+#maxCaptionLength: 1500
+
+# Reserved usernames that only the administrator can register with
+reservedUsernames: [
+  'root',
+  'admin',
+  'administrator',
+  'me',
+  'system'
+]
+
+# Whether disable HSTS
+#disableHsts: true
+
+# Number of worker processes
+#clusterLimit: 1
+
+# Worker only mode
+#onlyQueueProcessor: 1
+
+# Job concurrency per worker
+# deliverJobConcurrency: 128
+# inboxJobConcurrency: 16
+
+# Job rate limiter
+# deliverJobPerSec: 128
+# inboxJobPerSec: 16
+
+# Job attempts
+# deliverJobMaxAttempts: 12
+# inboxJobMaxAttempts: 8
+
+# IP address family used for outgoing request (ipv4, ipv6 or dual)
+#outgoingAddressFamily: ipv4
+
+# Syslog option
+#syslog:
+#  host: localhost
+#  port: 514
+
+# Proxy for HTTP/HTTPS
+#proxy: http://127.0.0.1:3128
+
+#proxyBypassHosts: [
+#  'web.kaiteki.app',
+#  'example.com',
+#  '192.0.2.8'
+#]
+
+# Proxy for SMTP/SMTPS
+#proxySmtp: http://127.0.0.1:3128   # use HTTP/1.1 CONNECT
+#proxySmtp: socks4://127.0.0.1:1080 # use SOCKS4
+#proxySmtp: socks5://127.0.0.1:1080 # use SOCKS5
+
+# Media Proxy
+#mediaProxy: https://example.com/proxy
+
+# Proxy remote files (default: false)
+#proxyRemoteFiles: true
+
+# Media cleanup settings (defaults: false, 0, false, false)
+#mediaCleanup:
+#  cron: true
+#  maxAgeDays: 30
+#  cleanAvatars: false
+#  cleanHeaders: false
+
+#allowedPrivateNetworks: [
+#  '127.0.0.1/32'
+#]
+
+# TWA
+#twa:
+#  nameSpace: android_app
+#  packageName: tld.domain.twa
+#  sha256CertFingerprints: ['AB:CD:EF']
+
+# Upload or download file size limits (bytes)
+#maxFileSize: 262144000
+
+#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Congrats, you've reached the end of the config file needed for most deployments!
+# Enjoy your Iceshrimp server!
+#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+
+
+#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Managed hosting settings
+# >>> NORMAL SELF-HOSTERS, STAY AWAY! <<<
+# >>> YOU DON'T NEED THIS! <<<
+# Each category is optional, but if each item in each category is mandatory!
+# If you mess this up, that's on you, you've been warned...
+#━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#maxUserSignups: 100
+#isManagedHosting: true
+#deepl:
+#  managed: true
+#  authKey: ''
+#  isPro: false
+#
+#email:
+#  managed: true
+#  address: 'example@email.com'
+#  host: 'email.com'
+#  port: 587
+#  user: 'example@email.com'
+#  pass: ''
+#  useImplicitSslTls: false
+#
+#objectStorage:
+#  managed: true
+#  baseUrl: ''
+#  bucket: ''
+#  prefix: ''
+#  endpoint: ''
+#  region: ''
+#  accessKey: ''
+#  secretKey: ''
+#  useSsl: true
+#  connnectOverProxy: false
+#  setPublicReadOnUpload: true
+#  s3ForcePathStyle: true
+
+# !!!!!!!!!!
+# >>>>>> AGAIN, NORMAL SELF-HOSTERS, STAY AWAY! <<<<<<
+# >>>>>> YOU DON'T NEED THIS, ABOVE SETTINGS ARE FOR MANAGED HOSTING ONLY! <<<<<<
+# !!!!!!!!!!
+
+# Seriously. Do NOT fill out the above settings if you're self-hosting.
+# They're much better off being set from the control panel.

docker-compose.yml.example

@@ -2,7 +2,7 @@ version: "3"
 
 services:
   web:
-    image: iceshrimp.dev/iceshrimp/iceshrimp:latest
+    image: iceshrimp.dev/iceshrimp/iceshrimp:dev
 ### If you want to build the image locally
 #    build: .
     container_name: iceshrimp_web
@@ -13,6 +13,10 @@ services:
 ### Uncomment one of the following to use a search engine
 #     - meilisearch
 #     - sonic
+### Uncomment one of the following to use a cache server
+#     - dragonflydb
+#     - keydb
+#     - redis_cache
     ports:
       - "3000:3000"
     networks:
@@ -44,12 +48,13 @@ services:
     volumes:
       - ./db:/var/lib/postgresql/data
 
+### Search Engines
 ### Only one of the below should be used.
 ### Meilisearch is better overall, but resource-intensive. Sonic is a very light full text search engine.
 
 #  meilisearch:
-#    container_name: meilisearch
-#    image: getmeili/meilisearch:v1.1.1
+#    container_name: iceshrimp_meilisearch
+#    image: docker.io/getmeili/meilisearch:v1.1.1
 #    environment:
 #      - MEILI_ENV=${MEILI_ENV:-development}
 #    ports:
@@ -61,6 +66,7 @@ services:
 #    restart: unless-stopped
 
 #  sonic:
+#    container_name: iceshrimp_sonic
 #    restart: unless-stopped
 #    image: docker.io/valeriansaliou/sonic:v1.4.0
 #    networks:
@@ -69,6 +75,40 @@ services:
 #      - ./sonic:/var/lib/sonic/store
 #      - ./sonic/config.cfg:/etc/sonic.cfg
 
+### Cache Servers
+### Only one of the below should be used.
+### DragonflyDB is the fastest overall, however it is NOT open source, but source-available (BSL). KeyDB is still faster than pure Redis, and it's BSD-licensed.
+#  dragonflydb:
+#    container_name: iceshrimp_dragonflydb
+#    restart: unless-stopped
+#    image: 'docker.dragonflydb.io/dragonflydb/dragonfly:v1.8.0'
+#    ulimits:
+#      memlock: -1
+#    networks:
+#      - ishnet
+#    volumes:
+#      - ./dragonflydb:/data
+
+#  keydb:
+#    container_name: iceshrimp_keydb
+#    restart: unless-stopped
+### Choose an image depending on your architecture, keydb doesn't build alpine for arm, and the way they do tags is very weird in general
+##    image: 'docker.io/eqalpha/keydb:alpine_x86_64_v6.3.3'
+##    image: 'docker.io/eqalpha/keydb:arm64_v6.3.3'
+#    networks:
+#      - ishnet
+#    volumes:
+#      - ./keydb:/data
+
+#  redis_cache:
+#    restart: unless-stopped
+#    image: docker.io/redis:7.0-alpine
+#    container_name: iceshrimp_redis_cache
+#    networks:
+#      - ishnet
+#    volumes:
+#      - ./redis_cache:/data
+
 networks:
   ishnet:
   #  web:

docs/docker-compose-install.md

@@ -0,0 +1,73 @@
+# Installing Iceshrimp with Docker
+
+This guide is based on `docker compose`/Docker Compose v2, but `docker-compose`/Docker Compose v1 will work as well.
+
+## Preparations
+
+### Getting needed files
+
+Run `git clone https://iceshrimp.dev/iceshrimp/iceshrimp` <!--but if you are not planning on building your own image, just grabbing `.config` and `docker-compose.yml.example` from the repo will suffice.-->
+
+### docker-compose.yml
+
+First, run `cp docker-compose.yml.example docker-compose.yml`, and edit `docker-compose.yml` if
+- you want to build the image yourself or choose a [different tag](https://iceshrimp.dev/iceshrimp/-/packages/container/iceshrimp/versions), and/or
+- you want a search engine for better search performance and/or a cache server for better antenna handling.
+
+### .config
+
+Run `cp .config/docker_example.env .config/docker.env`, and edit `.config/docker.env` and fill it with the database credentials you want.  
+Run `cp .config/example-docker.yml .config/default.yml`, and edit `.config/default.yml` 
+- Replace example database credentials with the ones you entered in `.config/docker.env`
+- Change other configuration
+- Optionally, set up the search engine and cache server, if you have chosen to set them up.
+
+## Installation and first start
+
+Choose a method, whether you chose to build the image yourself or not.  
+Note: Ctrl-C will shut down Iceshrimp gracefully.
+
+### Pulling the image
+
+```sh
+docker compose pull
+docker compose up
+```
+
+### Building the image
+
+Depending on your machine specs, this can take well over 30 minutes
+```sh
+docker compose build
+docker compose up
+```
+
+## Starting Iceshrimp automatically
+
+Run `docker compose up -d` and Iceshrimp will start automatically on boot.
+
+## Updating Iceshrimp
+
+### Pulling the image
+
+```sh
+docker compose pull
+docker compose down
+docker compose up -d
+```
+
+### Building the image
+
+```sh
+## Run git stash commands only if you have uncommitted changes
+git stash
+git pull
+git stash pop
+docker compose build
+docker compose down
+docker compose up -d
+```
+
+## Post-install
+
+See [post-install](post-install.md).