Activepieces, Docker Compose ve HTTPS ile nasıl kurulur

Activepieces açık kaynaklı bir otomasyon platformudur. Akışları tetikleyicilerden ve iş uygulamalarına ve yapay zeka servislerine bağlanan piece adlı adımlardan kurar, dallar, döngüler ve kod adımları ekler, akışları yapay zeka ajanlarına araç olarak sunarsınız. Akış oluşturucusu geliştiricilerin yanında iş kullanıcılarını da hedefler; kendi sunucunuzda çalıştırmak ise bağlantıları ve çalıştırma verilerini sizin sunucunuzda tutar.

Bu rehber Activepieces belgelerindeki Docker Compose yöntemini izler: resmi depoyu klonlar, gizli değerleri depodaki tools/deploy.sh betiğiyle üretir ve app servisini, bir worker'ı, PostgreSQL'i ve Redis'i Docker Compose ile çalıştırırsınız. Uygulama yalnızca 127.0.0.1 üzerinde dinler, Caddy ise onu alan adınızda HTTPS ile sunar. Ardından platform yöneticisi hesabını oluşturur, yedekleme ve güncellemeyi ayarlarsınız. Kısa bir bölüm, alternatif olarak resmi tek komutluk kurulum aracını açıklar.

Adım 1 — Resmi depoyu klonlayın

Depo, .env.example şablonunu ve gizli değer üreticisini içerir. Depoyu /opt/activepieces klasörüne klonlayın; sığ (shallow) bir klon yeterlidir:

sudo apt update
sudo apt install git openssl
sudo mkdir -p /opt/activepieces
sudo chown $USER:$USER /opt/activepieces
git clone --depth 1 https://github.com/activepieces/activepieces.git /opt/activepieces
cd /opt/activepieces

Adım 2 — Gizli değerleri resmi betikle üretin

tools/deploy.sh, .env.example dosyasını .env olarak kopyalar ve openssl ile rastgele değerler doldurur: AP_API_KEY, AP_POSTGRES_PASSWORD, AP_JWT_SECRET (oturum token'larını imzalar) ve AP_ENCRYPTION_KEY (kaydettiğiniz bağlantıları şifreleyen 32 onaltılık karakter). Betiği bir kez çalıştırın ve önemli değerlerin boş olmadığını kontrol edin:

sh tools/deploy.sh
grep -E '^(AP_ENCRYPTION_KEY|AP_JWT_SECRET|AP_POSTGRES_PASSWORD)=' .env
chmod 600 .env

Üç satırın da uzun bir değer göstermesi gerekir. Activepieces belgeleri, openssl eksikse betiğin boş değerlerle başarı bildirebileceği konusunda uyarır.

Adım 3 — Temel ayarları yapılandırın

.env içindeki üç ayar dikkatinizi gerektirir:

• AP_FRONTEND_URL, yönlendirmeler, OAuth geri dönüşleri ve webhook adresleri için kullanılan genel adrestir. Harici servislerin bu adrese erişebilmesi gerekir.
• AP_EDITION=ee, Activepieces'in Docker Compose belgelerinin ve kurulum aracının ayarladığı değerdir. Aşağıda gösterildiği gibi ekleyin.
• AP_EXECUTION_MODE, kod adımlarının nasıl yalıtılacağını belirler. AP_EDITION=ee ile sunucu varsayılan UNSANDBOXED değeriyle başlamayı reddeder; bu nedenle SANDBOX_CODE_ONLY ayarlayın: her kod adımı 128 MB belleğe sahip, dosya sistemi erişimi olmayan yeni bir V8 isolate içinde çalışır. Activepieces bu modu, kullanıcıların tamamına güvenilmediği durumlar için önerir. Bu modda kod adımları npm paketlerini kullanamaz.

Sonraki adımdaki Compose dosyası, çalıştırılacak imaj etiketi olan AP_VERSION değerini de okur. 2026-10-09 tarihindeki en yeni sürüm 0.92.2 idi; GitHub'daki Activepieces sürümler sayfasından güncel etiketi kullanın:

cd /opt/activepieces
sed -i 's|^AP_FRONTEND_URL=.*|AP_FRONTEND_URL=https://automation.example.com|' .env
sed -i 's|^AP_EXECUTION_MODE=.*|AP_EXECUTION_MODE=SANDBOX_CODE_ONLY|' .env
cat >> .env <<'EOF'
AP_EDITION=ee
AP_VERSION=0.92.2
EOF
grep -E '^AP_(FRONTEND_URL|EXECUTION_MODE|EDITION|VERSION)=' .env

Son komut az önce ayarladığınız dört değeri yazdırmalıdır.

Adım 4 — Compose dosyasını uyarlayın

Depodaki docker-compose.yml, 8080 numaralı portu tüm adreslerde yayınlar, veritabanına ve Redis'e sabit konteyner adları verir ve beş worker başlatır. Orijinalin bir kopyasını saklayın ve dosyayı aşağıdaki sürümle değiştirin. Bu sürüm, Activepieces'in kendi kurulum aracının yazdığı şablonla aynıdır; yalnızca iki fark vardır: port sadece 127.0.0.1 üzerinde yayınlanır ve imaj etiketi AP_VERSION değerinden gelir:

cp docker-compose.yml docker-compose.yml.orig
nano docker-compose.yml

services:
  app:
    image: ghcr.io/activepieces/activepieces:${AP_VERSION}
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    depends_on:
      - postgres
      - redis
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=APP
    volumes:
      - ./cache:/usr/src/app/cache
    networks:
      - activepieces
  worker:
    image: ghcr.io/activepieces/activepieces:${AP_VERSION}
    restart: unless-stopped
    depends_on:
      - app
    env_file: .env
    environment:
      - AP_CONTAINER_TYPE=WORKER
      - AP_FRONTEND_URL=http://app
    volumes:
      - ./cache:/usr/src/app/cache
    networks:
      - activepieces
  postgres:
    image: pgvector/pgvector:0.8.0-pg14
    restart: unless-stopped
    env_file: .env
    environment:
      - POSTGRES_DB=${AP_POSTGRES_DATABASE}
      - POSTGRES_PASSWORD=${AP_POSTGRES_PASSWORD}
      - POSTGRES_USER=${AP_POSTGRES_USERNAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - activepieces
  redis:
    image: redis:7.0.7
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - activepieces
volumes:
  postgres_data:
  redis_data:
networks:
  activepieces:

Worker'ın kendi AP_FRONTEND_URL=http://app değeri .env içindeki genel adresi geçersiz kılar: worker'lar app servisiyle iç ağ üzerinden konuşur ve worker konteynerinin içindeki localhost worker'ın kendisini gösterir. Dosyada sözdizimi hatası olmadığını kontrol edin:

docker compose config --quiet && echo "compose file OK"

Adım 5 — Activepieces'i başlatın

İmajları çekin ve yapıyı başlatın. İlk açılış, uygulama veritabanı tablolarını oluştururken bir iki dakika sürer:

docker compose pull
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:8080/api/v1/health

Dört servisin de running durumunda olması gerekir; uygulama hazır olduğunda sağlık uç noktası kısa bir JSON durumuyla yanıt verir. Vermiyorsa uygulama logunu docker compose logs -f app ile izleyin.

Adım 6 — Activepieces'i Caddy ile HTTPS üzerinden yayınlayın

/etc/caddy/Caddyfile dosyasına alt alan adı için bir site bloğu ekleyin:

automation.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy'yi yeniden yükleyin, yalnızca SSH ve web trafiğine izin verin ve genel adresi test edin:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -I https://automation.example.com

Geçerli bir sertifikayla HTTP 200 yanıtı almalısınız. Docker portu yalnızca loopback adresinde yayınladığı için 8080 numaralı port internete kapalı kalır. Caddy yerine Nginx veya Traefik için Nginx ve Certbot ile Traefik rehberlerine bakın.

Adım 7 — Platform yöneticisi hesabını oluşturun

https://automation.example.com adresini hemen açın ve kayıt olun. Yeni bir kurulumda ilk hesap platform yöneticisi olur. Bundan sonra yeni kişiler yönetim konsolundan gönderilen davetlerle katılır; açık kayıt yalnızca AP_ALLOW_OPEN_SIGN_UP=true ayarlarsanız mümkündür ve bunu herkese açık bir sunucuda yapmamalısınız.

Ardından Platform Admin → Operations → Workers ekranını açın ve en az bir worker'ın listelendiğini kontrol edin. Davetlerin ve e-postayla gönderilen altı haneli giriş kodlarının çalışması için yönetim konsolunda giden e-postayı yapılandırın. Alternatif olarak .env içinde AP_SMTP_HOST (örneğin smtp.example.com), AP_SMTP_PORT (587), AP_SMTP_USERNAME, AP_SMTP_PASSWORD, AP_SMTP_SENDER_EMAIL ve AP_SMTP_SENDER_NAME değerlerini ayarlayabilirsiniz; Activepieces bu değişkenleri yalnızca yönetim ekranında e-posta yapılandırması yoksa ve host, port, kullanıcı adı ve parolanın tümü ayarlıysa kullanır. Parolası olan kullanıcılar Use password bağlantısıyla her zaman giriş yapabilir.

Daha fazla akışı paralel çalıştırmak için docker compose up -d --scale worker=2 ile worker ekleyin. Activepieces'in üretim önerileri, çok sayıda paralel iş çalıştıran tek bir worker yerine AP_WORKER_CONCURRENCY=1 ayarlı birkaç worker'ı tercih eder; böylece bellek yetersizliği hatası yalnızca tek bir çalıştırmayı etkiler.

Alternatif: tek komutluk kurulum aracı

Activepieces, get.activepieces.com adresinde resmi bir kurulum aracı da sunar. Araç Docker Compose v2'yi kontrol eder, bir docker-compose.yml ve üretilmiş gizli değerlerle dolu bir .env (AP_EDITION=ee, SANDBOX_CODE_ONLY) içeren bir activepieces klasörü oluşturur, en yeni sürümü çeker ve yapıyı başlatır. Mevcut bir .env dosyasının üzerine asla yazmaz; aynı betik --upgrade ve --uninstall işlemlerini de yapar. Çalıştırmadan önce indirin ve okuyun:

curl -fsSL https://get.activepieces.com -o install-activepieces.sh
less install-activepieces.sh
sh install-activepieces.sh --dir /opt/activepieces

Resmi tek satırlık biçim aynı betiği doğrudan sh'a aktarır. Kurulum aracının uygulamayı 8080 numaralı portta tüm adreslerde yayınladığını ve AP_FRONTEND_URL değerini http://localhost:8080 olarak ayarladığını unutmayın; Docker ufw'yi atlar, bu yüzden siz değiştirene kadar port internetten erişilebilir olur. Yönetici hesabını hemen oluşturun, ardından üretilen .env içinde AP_HOST_PORT=127.0.0.1:8080 ve HTTPS AP_FRONTEND_URL değerlerini ayarlayıp o klasörde docker compose up -d ile uygulayın.

Yedekleme ve geri yükleme

Activepieces akışları, çalıştırmaları, bağlantıları ve kullanıcıları proje klasöründe değil, postgres_data volume'undaki PostgreSQL'de tutar. İkinci temel öğe şifreleme anahtarını içeren .env dosyasıdır. Redis yalnızca iş kuyruğunu tutar; cache klasörü de kendiliğinden yeniden oluşturulur. Veritabanını ve yapılandırmayı yedekleyin:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
cd /opt/activepieces
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' > /opt/backups/activepieces-db-$(date +%F).dump
tar czf /opt/backups/activepieces-config-$(date +%F).tar.gz -C /opt/activepieces .env docker-compose.yml
chmod 600 /opt/backups/activepieces-*

Aynı sunucuya veya yeni bir sunucuya geri yüklemek için arşivdeki .env ve docker-compose.yml dosyalarını /opt/activepieces içine koyun, PostgreSQL'i tek başına başlatın, dökümü yükleyin ve kalan servisleri başlatın:

cd /opt/activepieces
docker compose stop app worker
docker compose up -d postgres
until docker compose exec postgres pg_isready -U postgres; do sleep 2; done
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' < /opt/backups/activepieces-db-2026-10-09.dump
docker compose up -d

Tarihi kendi dosya adınızdaki tarihle değiştirin. /opt/backups klasörünü düzenli olarak başka bir makineye veya nesne depolamaya kopyalayın; aynı sunucuda kalan yedekler sunucuyla birlikte kaybolur.

Activepieces güncelleme

Activepieces sık sürüm yayınlar. Her güncellemeden önce belgelerindeki, kendi sunucunuzdaki kurulumları ve tek tek piece'leri etkileyen değişiklikleri listeleyen breaking changes sayfasını okuyun; veritabanını ve .env dosyasını yedekleyin. Ardından .env içindeki AP_VERSION değerini yeni sürüme ayarlayın ve konteynerleri yeniden oluşturun:

cd /opt/activepieces
nano .env
docker compose pull
docker compose up -d
docker compose logs --tail=50 app

Veritabanı geçişleri uygulama başlarken çalışır. Sıradan güncellemelerde PostgreSQL ve Redis imaj etiketlerini olduğu gibi bırakın; PostgreSQL ana sürüm yükseltmesi döküm alıp geri yüklemeyi gerektirir. Tek komutluk kurulum aracını kullandıysanız bunun yerine aracı --upgrade ile yeniden çalıştırın; araç AP_VERSION değerini günceller, .env dosyanızı ve verilerinizi korur.

Sorun giderme

Webhook ve yönlendirme adresleri localhost:8080 gösteriyor

.env içindeki AP_FRONTEND_URL hâlâ varsayılan değerinde. Değeri https://automation.example.com yapın ve docker compose up -d --force-recreate app çalıştırın. Değişiklikten önce harici servislere kopyalanan webhook adreslerinin orada da güncellenmesi gerekir.

Akışlar kuyrukta bekliyor ve hiç worker listelenmiyor

Worker app servisine ulaşamıyor. Worker servisinin AP_FRONTEND_URL=http://app ayarladığından ve iki konteynerin de activepieces ağını paylaştığından emin olun, ardından docker compose logs worker çıktısını okuyun. Platform Admin → Operations → Workers ekranında en az bir worker listelenmelidir.

AP_EDITION=ee ile uygulama açılır açılmaz duruyor

AP_EDITION=ee ile sunucu başlangıçta AP_EXECUTION_MODE=UNSANDBOXED değerini reddeder. .env içinde AP_EXECUTION_MODE=SANDBOX_CODE_ONLY ayarlayın ve docker compose up -d çalıştırın. SANDBOX_PROCESS ve SANDBOX_CODE_AND_PROCESS modları ayrıcalıklı konteyner gerektirir ve bu rehberde kullanılmaz.

Geri yüklemeden sonra bağlantılar çalışmıyor

Geçerli .env içindeki AP_ENCRYPTION_KEY, verileri şifreleyen anahtar değil. Orijinal .env dosyasını geri koyun ve konteynerleri yeniden oluşturun. Orijinal anahtar olmadan kayıtlı bağlantılar kurtarılamaz ve yeniden bağlanmaları gerekir.

Bir kod adımı npm paketi içe aktaramıyor

SANDBOX_CODE_ONLY, kodu require veya npm olmadan bir V8 isolate içinde çalıştırır. Mantığı bir piece'e taşıyın veya bunun yerine harici bir API çağırın.

8080 numaralı port zaten kullanımda

Loopback adresinde 8080 numaralı portu başka bir servis kullanıyor. Eşlemenin sunucu tarafını değiştirin, örneğin "127.0.0.1:8081:80", Caddy site bloğunu buna göre güncelleyin ve docker compose up -d çalıştırın. Uygulamanın iç dinleme portu olan AP_PORT değerini değiştirmeyin.

Sonraki adımlar

• Activepieces'i n8n ve Node-RED ile karşılaştırın.
• Compose dosyaları hakkında daha fazlasını Docker Compose temelleri rehberinde öğrenin.
• Otomasyon iş yüklerine göre boyutlandırılmış sunucuları Activepieces hosting sayfasında bulun.
• Ortam değişkenleri, sandbox ve ölçekleme için Activepieces self-hosting belgelerini okuyun.