diff --git a/docs/404.html b/docs/404.html
index 6841a8463..3267fb99d 100644
--- a/docs/404.html
+++ b/docs/404.html
@@ -2834,11 +2834,11 @@
   
   
     <li class="md-nav__item">
-      <a href="/docs/deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="/docs/deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/backup-recovery/index.html b/docs/advanced-usage/backup-recovery/index.html
index 3a20eccd8..7fbbce679 100644
--- a/docs/advanced-usage/backup-recovery/index.html
+++ b/docs/advanced-usage/backup-recovery/index.html
@@ -3015,11 +3015,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/deployment-tasks/index.html b/docs/advanced-usage/deployment-tasks/index.html
index 4ac18d264..d907baffc 100644
--- a/docs/advanced-usage/deployment-tasks/index.html
+++ b/docs/advanced-usage/deployment-tasks/index.html
@@ -2970,11 +2970,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/docker-options/index.html b/docs/advanced-usage/docker-options/index.html
index 716e1d1d0..cc4e999e3 100644
--- a/docs/advanced-usage/docker-options/index.html
+++ b/docs/advanced-usage/docker-options/index.html
@@ -2955,11 +2955,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/event-logs/index.html b/docs/advanced-usage/event-logs/index.html
index fd785dbc5..e34bc42fb 100644
--- a/docs/advanced-usage/event-logs/index.html
+++ b/docs/advanced-usage/event-logs/index.html
@@ -2904,11 +2904,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/persistent-storage/index.html b/docs/advanced-usage/persistent-storage/index.html
index 4cfe6cfea..124a4621c 100644
--- a/docs/advanced-usage/persistent-storage/index.html
+++ b/docs/advanced-usage/persistent-storage/index.html
@@ -3024,11 +3024,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/plugin-management/index.html b/docs/advanced-usage/plugin-management/index.html
index bb95596de..e8080664b 100644
--- a/docs/advanced-usage/plugin-management/index.html
+++ b/docs/advanced-usage/plugin-management/index.html
@@ -2991,11 +2991,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/registry-management/index.html b/docs/advanced-usage/registry-management/index.html
index ed95b33e2..ee510da94 100644
--- a/docs/advanced-usage/registry-management/index.html
+++ b/docs/advanced-usage/registry-management/index.html
@@ -2955,11 +2955,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/repository-management/index.html b/docs/advanced-usage/repository-management/index.html
index 54822834a..2b5159b81 100644
--- a/docs/advanced-usage/repository-management/index.html
+++ b/docs/advanced-usage/repository-management/index.html
@@ -2928,11 +2928,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/advanced-usage/resource-management/index.html b/docs/advanced-usage/resource-management/index.html
index 87c0ccd3e..eafbc8900 100644
--- a/docs/advanced-usage/resource-management/index.html
+++ b/docs/advanced-usage/resource-management/index.html
@@ -2985,11 +2985,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.10.0-migration-guide/index.html b/docs/appendices/0.10.0-migration-guide/index.html
index 094e968e1..c60038091 100644
--- a/docs/appendices/0.10.0-migration-guide/index.html
+++ b/docs/appendices/0.10.0-migration-guide/index.html
@@ -2915,11 +2915,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.20.0-migration-guide/index.html b/docs/appendices/0.20.0-migration-guide/index.html
index 921a2eedb..aef9ed687 100644
--- a/docs/appendices/0.20.0-migration-guide/index.html
+++ b/docs/appendices/0.20.0-migration-guide/index.html
@@ -3008,11 +3008,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.21.0-migration-guide/index.html b/docs/appendices/0.21.0-migration-guide/index.html
index a08badac7..622c8f18b 100644
--- a/docs/appendices/0.21.0-migration-guide/index.html
+++ b/docs/appendices/0.21.0-migration-guide/index.html
@@ -2924,11 +2924,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.22.0-migration-guide/index.html b/docs/appendices/0.22.0-migration-guide/index.html
index 70ad54e0b..b412fb2b2 100644
--- a/docs/appendices/0.22.0-migration-guide/index.html
+++ b/docs/appendices/0.22.0-migration-guide/index.html
@@ -2924,11 +2924,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.23.0-migration-guide/index.html b/docs/appendices/0.23.0-migration-guide/index.html
index 048877130..a8dc923dc 100644
--- a/docs/appendices/0.23.0-migration-guide/index.html
+++ b/docs/appendices/0.23.0-migration-guide/index.html
@@ -2906,11 +2906,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.24.0-migration-guide/index.html b/docs/appendices/0.24.0-migration-guide/index.html
index f6fd63b9c..a6b25fb78 100644
--- a/docs/appendices/0.24.0-migration-guide/index.html
+++ b/docs/appendices/0.24.0-migration-guide/index.html
@@ -2915,11 +2915,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.25.0-migration-guide/index.html b/docs/appendices/0.25.0-migration-guide/index.html
index 30948a142..05b002d79 100644
--- a/docs/appendices/0.25.0-migration-guide/index.html
+++ b/docs/appendices/0.25.0-migration-guide/index.html
@@ -2948,11 +2948,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.26.0-migration-guide/index.html b/docs/appendices/0.26.0-migration-guide/index.html
index aba7d6875..ee471c7c8 100644
--- a/docs/appendices/0.26.0-migration-guide/index.html
+++ b/docs/appendices/0.26.0-migration-guide/index.html
@@ -2915,11 +2915,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.27.0-migration-guide/index.html b/docs/appendices/0.27.0-migration-guide/index.html
index 44773a7be..63b7d8865 100644
--- a/docs/appendices/0.27.0-migration-guide/index.html
+++ b/docs/appendices/0.27.0-migration-guide/index.html
@@ -2906,11 +2906,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.28.0-migration-guide/index.html b/docs/appendices/0.28.0-migration-guide/index.html
index b1bb55b2b..da79f4a0f 100644
--- a/docs/appendices/0.28.0-migration-guide/index.html
+++ b/docs/appendices/0.28.0-migration-guide/index.html
@@ -2924,11 +2924,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.29.0-migration-guide/index.html b/docs/appendices/0.29.0-migration-guide/index.html
index eada5382a..1f607c6f5 100644
--- a/docs/appendices/0.29.0-migration-guide/index.html
+++ b/docs/appendices/0.29.0-migration-guide/index.html
@@ -2915,11 +2915,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.30.0-migration-guide/index.html b/docs/appendices/0.30.0-migration-guide/index.html
index 536876555..76c1cde6c 100644
--- a/docs/appendices/0.30.0-migration-guide/index.html
+++ b/docs/appendices/0.30.0-migration-guide/index.html
@@ -2924,11 +2924,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.31.0-migration-guide/index.html b/docs/appendices/0.31.0-migration-guide/index.html
index 7e784b0c0..b7f317800 100644
--- a/docs/appendices/0.31.0-migration-guide/index.html
+++ b/docs/appendices/0.31.0-migration-guide/index.html
@@ -2933,11 +2933,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.32.0-migration-guide/index.html b/docs/appendices/0.32.0-migration-guide/index.html
index 40083ee4c..d8897195b 100644
--- a/docs/appendices/0.32.0-migration-guide/index.html
+++ b/docs/appendices/0.32.0-migration-guide/index.html
@@ -2915,11 +2915,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.5.0-migration-guide/index.html b/docs/appendices/0.5.0-migration-guide/index.html
index 158b2de7b..cc3799d68 100644
--- a/docs/appendices/0.5.0-migration-guide/index.html
+++ b/docs/appendices/0.5.0-migration-guide/index.html
@@ -2915,11 +2915,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.6.0-migration-guide/index.html b/docs/appendices/0.6.0-migration-guide/index.html
index b12a74de1..2f189766b 100644
--- a/docs/appendices/0.6.0-migration-guide/index.html
+++ b/docs/appendices/0.6.0-migration-guide/index.html
@@ -2924,11 +2924,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.7.0-migration-guide/index.html b/docs/appendices/0.7.0-migration-guide/index.html
index d59e51bfe..970a90a06 100644
--- a/docs/appendices/0.7.0-migration-guide/index.html
+++ b/docs/appendices/0.7.0-migration-guide/index.html
@@ -2924,11 +2924,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.8.0-migration-guide/index.html b/docs/appendices/0.8.0-migration-guide/index.html
index e1c43733c..5a71ed637 100644
--- a/docs/appendices/0.8.0-migration-guide/index.html
+++ b/docs/appendices/0.8.0-migration-guide/index.html
@@ -2933,11 +2933,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/appendices/0.9.0-migration-guide/index.html b/docs/appendices/0.9.0-migration-guide/index.html
index de6ab4c42..5f645c7f3 100644
--- a/docs/appendices/0.9.0-migration-guide/index.html
+++ b/docs/appendices/0.9.0-migration-guide/index.html
@@ -2906,11 +2906,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/community/clients/index.html b/docs/community/clients/index.html
index 4c4aa8d32..072f00573 100644
--- a/docs/community/clients/index.html
+++ b/docs/community/clients/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/community/plugins/index.html b/docs/community/plugins/index.html
index 870f71ae3..dfc63f845 100644
--- a/docs/community/plugins/index.html
+++ b/docs/community/plugins/index.html
@@ -2851,11 +2851,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/configuration/domains/index.html b/docs/configuration/domains/index.html
index 4ef5601fa..9290dbe4d 100644
--- a/docs/configuration/domains/index.html
+++ b/docs/configuration/domains/index.html
@@ -2931,11 +2931,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/configuration/environment-variables/index.html b/docs/configuration/environment-variables/index.html
index 12cfaf6ef..6c0319e96 100644
--- a/docs/configuration/environment-variables/index.html
+++ b/docs/configuration/environment-variables/index.html
@@ -2904,11 +2904,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/configuration/ssl/index.html b/docs/configuration/ssl/index.html
index ae8f61965..924f14ab0 100644
--- a/docs/configuration/ssl/index.html
+++ b/docs/configuration/ssl/index.html
@@ -3027,11 +3027,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/application-deployment/index.html b/docs/deployment/application-deployment/index.html
index 6d79150e2..6d59457a6 100644
--- a/docs/deployment/application-deployment/index.html
+++ b/docs/deployment/application-deployment/index.html
@@ -3081,11 +3081,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/application-management/index.html b/docs/deployment/application-management/index.html
index 6b21a2960..07fdebe63 100644
--- a/docs/deployment/application-management/index.html
+++ b/docs/deployment/application-management/index.html
@@ -3000,11 +3000,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/builder-management/index.html b/docs/deployment/builders/builder-management/index.html
index 621ad451f..40ade1c84 100644
--- a/docs/deployment/builders/builder-management/index.html
+++ b/docs/deployment/builders/builder-management/index.html
@@ -2961,11 +2961,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/cloud-native-buildpacks/index.html b/docs/deployment/builders/cloud-native-buildpacks/index.html
index dd3babfbb..69ccc07d6 100644
--- a/docs/deployment/builders/cloud-native-buildpacks/index.html
+++ b/docs/deployment/builders/cloud-native-buildpacks/index.html
@@ -2973,11 +2973,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/dockerfiles/index.html b/docs/deployment/builders/dockerfiles/index.html
index e8c37594a..69f57c3df 100644
--- a/docs/deployment/builders/dockerfiles/index.html
+++ b/docs/deployment/builders/dockerfiles/index.html
@@ -3006,11 +3006,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/herokuish-buildpacks/index.html b/docs/deployment/builders/herokuish-buildpacks/index.html
index 1ab178349..b90c6a513 100644
--- a/docs/deployment/builders/herokuish-buildpacks/index.html
+++ b/docs/deployment/builders/herokuish-buildpacks/index.html
@@ -3060,11 +3060,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/lambda/index.html b/docs/deployment/builders/lambda/index.html
index aad68addf..f94a55e27 100644
--- a/docs/deployment/builders/lambda/index.html
+++ b/docs/deployment/builders/lambda/index.html
@@ -2955,11 +2955,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/nixpacks/index.html b/docs/deployment/builders/nixpacks/index.html
index 8271ab477..b84727ee3 100644
--- a/docs/deployment/builders/nixpacks/index.html
+++ b/docs/deployment/builders/nixpacks/index.html
@@ -2973,11 +2973,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/builders/null/index.html b/docs/deployment/builders/null/index.html
index e0397e894..de73f6013 100644
--- a/docs/deployment/builders/null/index.html
+++ b/docs/deployment/builders/null/index.html
@@ -2919,11 +2919,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/continuous-integration/generic/index.html b/docs/deployment/continuous-integration/generic/index.html
index bcb48dcd4..c8f3b1ea9 100644
--- a/docs/deployment/continuous-integration/generic/index.html
+++ b/docs/deployment/continuous-integration/generic/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/continuous-integration/github-actions/index.html b/docs/deployment/continuous-integration/github-actions/index.html
index c2313884b..e8212381a 100644
--- a/docs/deployment/continuous-integration/github-actions/index.html
+++ b/docs/deployment/continuous-integration/github-actions/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/continuous-integration/gitlab-ci/index.html b/docs/deployment/continuous-integration/gitlab-ci/index.html
index 3d8c28186..0333d6c92 100644
--- a/docs/deployment/continuous-integration/gitlab-ci/index.html
+++ b/docs/deployment/continuous-integration/gitlab-ci/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/logs/index.html b/docs/deployment/logs/index.html
index 5cdc45c49..65d89fc60 100644
--- a/docs/deployment/logs/index.html
+++ b/docs/deployment/logs/index.html
@@ -3018,11 +3018,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/methods/archive/index.html b/docs/deployment/methods/archive/index.html
index 9e555dba7..5be479253 100644
--- a/docs/deployment/methods/archive/index.html
+++ b/docs/deployment/methods/archive/index.html
@@ -2904,11 +2904,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/methods/git/index.html b/docs/deployment/methods/git/index.html
index 7bb24e3cb..78780dd6b 100644
--- a/docs/deployment/methods/git/index.html
+++ b/docs/deployment/methods/git/index.html
@@ -2991,11 +2991,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/methods/image/index.html b/docs/deployment/methods/image/index.html
index 1b62f249f..ca5e462a9 100644
--- a/docs/deployment/methods/image/index.html
+++ b/docs/deployment/methods/image/index.html
@@ -2913,11 +2913,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/remote-commands/index.html b/docs/deployment/remote-commands/index.html
index 7f9ebf2e1..936a772de 100644
--- a/docs/deployment/remote-commands/index.html
+++ b/docs/deployment/remote-commands/index.html
@@ -2970,11 +2970,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/schedulers/docker-local/index.html b/docs/deployment/schedulers/docker-local/index.html
index e314b38b2..8624bf4f6 100644
--- a/docs/deployment/schedulers/docker-local/index.html
+++ b/docs/deployment/schedulers/docker-local/index.html
@@ -33,7 +33,7 @@
         <link rel="prev" href="../scheduler-management/">
       
       
-        <link rel="next" href="../kubernetes/">
+        <link rel="next" href="../k3s/">
       
       
       <link rel="icon" href="../../../assets/favicons/favicon-96x96.png">
@@ -3027,11 +3027,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../kubernetes/" class="md-nav__link">
+      <a href="../k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
@@ -3897,13 +3897,13 @@ <h4 id="resource-reservations">Resource Reservations<a class="headerlink" href="
         
         
           
-          <a href="../kubernetes/" class="md-footer__link md-footer__link--next" aria-label="Next: Kubernetes Scheduler">
+          <a href="../k3s/" class="md-footer__link md-footer__link--next" aria-label="Next: K3s Scheduler">
             <div class="md-footer__title">
               <span class="md-footer__direction">
                 Next
               </span>
               <div class="md-ellipsis">
-                Kubernetes Scheduler
+                K3s Scheduler
               </div>
             </div>
             <div class="md-footer__button md-icon">
diff --git a/docs/deployment/schedulers/k3s/index.html b/docs/deployment/schedulers/k3s/index.html
index e7e5fd965..7943e767e 100644
--- a/docs/deployment/schedulers/k3s/index.html
+++ b/docs/deployment/schedulers/k3s/index.html
@@ -30,6 +30,10 @@
         <link rel="canonical" href="https://dokku.com/docs/deployment/schedulers/k3s/">
       
       
+        <link rel="prev" href="../docker-local/">
+      
+      
+        <link rel="next" href="../nomad/">
       
       
       <link rel="icon" href="../../../assets/favicons/favicon-96x96.png">
@@ -264,22 +268,28 @@
         
   
   
+    
+  
   
     
     
       
   
   
+    
+  
   
     
     
       
   
+  
+    
   
   
     
     
-      <li class="md-tabs__item">
+      <li class="md-tabs__item md-tabs__item--active">
         <a href="../../../getting-started/installation/" class="md-tabs__link">
           
   
@@ -415,6 +425,8 @@
       
   
   
+    
+  
   
   
     
@@ -455,12 +467,12 @@
       
       
     
-    <li class="md-nav__item md-nav__item--section md-nav__item--nested">
+    <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
       
         
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" checked>
         
           
           <label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="">
@@ -474,7 +486,7 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="true">
           <label class="md-nav__title" for="__nav_1">
             <span class="md-nav__icon md-icon"></span>
             Docs
@@ -2744,6 +2756,8 @@
                 
   
   
+    
+  
   
   
     
@@ -2766,12 +2780,12 @@
       
       
     
-    <li class="md-nav__item md-nav__item--section md-nav__item--nested">
+    <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
       
         
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1_11" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1_11" checked>
         
           
           <label class="md-nav__link" for="__nav_1_11" id="__nav_1_11_label" tabindex="">
@@ -2785,7 +2799,7 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_1_11_label" aria-expanded="false">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_1_11_label" aria-expanded="true">
           <label class="md-nav__title" for="__nav_1_11">
             <span class="md-nav__icon md-icon"></span>
             Schedulers
@@ -2838,18 +2852,301 @@
                 
   
   
+    
+  
   
   
-    <li class="md-nav__item">
-      <a href="../kubernetes/" class="md-nav__link">
+    <li class="md-nav__item md-nav__item--active">
+      
+      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
+      
+      
+        
+      
+      
+        <label class="md-nav__link md-nav__link--active" for="__toc">
+          
+  
+  <span class="md-ellipsis">
+    K3s Scheduler
+  </span>
+  
+
+          <span class="md-nav__icon md-icon"></span>
+        </label>
+      
+      <a href="./" class="md-nav__link md-nav__link--active">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
       </a>
+      
+        
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+  
+  
+  
+    
+  
+  
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#usage" class="md-nav__link">
+    <span class="md-ellipsis">
+      Usage
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Usage">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#initializing-a-cluster" class="md-nav__link">
+    <span class="md-ellipsis">
+      Initializing a cluster
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#adding-nodes-to-the-cluster" class="md-nav__link">
+    <span class="md-ellipsis">
+      Adding nodes to the cluster
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Adding nodes to the cluster">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#adding-a-worker-node" class="md-nav__link">
+    <span class="md-ellipsis">
+      Adding a worker node
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#adding-a-server-node" class="md-nav__link">
+    <span class="md-ellipsis">
+      Adding a server node
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#changing-the-network-interface" class="md-nav__link">
+    <span class="md-ellipsis">
+      Changing the network interface
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#changing-deploy-timeouts" class="md-nav__link">
+    <span class="md-ellipsis">
+      Changing deploy timeouts
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#customizing-the-namespace" class="md-nav__link">
+    <span class="md-ellipsis">
+      Customizing the namespace
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#enabling-rollback-on-failure" class="md-nav__link">
+    <span class="md-ellipsis">
+      Enabling rollback on failure
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#using-image-pull-secrets" class="md-nav__link">
+    <span class="md-ellipsis">
+      Using image pull secrets
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Using image pull secrets">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#enabling-letsencrypt-integration" class="md-nav__link">
+    <span class="md-ellipsis">
+      Enabling letsencrypt integration
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#customizing-the-letsencrypt-server" class="md-nav__link">
+    <span class="md-ellipsis">
+      Customizing the letsencrypt server
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#using-kubectl-remotely" class="md-nav__link">
+    <span class="md-ellipsis">
+      Using kubectl remotely
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tutorial" class="md-nav__link">
+    <span class="md-ellipsis">
+      Tutorial
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Tutorial">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#single-node-cluster" class="md-nav__link">
+    <span class="md-ellipsis">
+      Single-node cluster
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#running-a-multi-cluster-node" class="md-nav__link">
+    <span class="md-ellipsis">
+      Running a multi-cluster node
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#scheduler-interface" class="md-nav__link">
+    <span class="md-ellipsis">
+      Scheduler Interface
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Scheduler Interface">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#implemented-commands-and-triggers" class="md-nav__link">
+    <span class="md-ellipsis">
+      Implemented Commands and Triggers
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unimplemented-command-functionality" class="md-nav__link">
+    <span class="md-ellipsis">
+      Unimplemented command functionality
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#logging-support" class="md-nav__link">
+    <span class="md-ellipsis">
+      Logging support
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#supported-resource-management-properties" class="md-nav__link">
+    <span class="md-ellipsis">
+      Supported Resource Management Properties
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Supported Resource Management Properties">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#resource-limits" class="md-nav__link">
+    <span class="md-ellipsis">
+      Resource Limits
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#resource-reservations" class="md-nav__link">
+    <span class="md-ellipsis">
+      Resource Reservations
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+      
     </li>
   
 
@@ -3650,15 +3947,23 @@
 
 
 <h1 id="k3s-scheduler">K3s Scheduler<a class="headerlink" href="#k3s-scheduler" title="Permanent link">&para;</a></h1>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>scheduler-k3s:initialize                           # initializes a cluster
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>scheduler-k3s:add-server [user:password@host:port] # adds a server node to a Dokku-managed cluster
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>scheduler-k3s:add-client [user:password@host:port] # adds a client node to a Dokku-managed cluster
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>scheduler-k3s:set [&lt;app&gt;|--global] &lt;key&gt; (&lt;value&gt;) # Set or clear a scheduler-k3s property for an app or the scheduler
-</code></pre></div>
 <div class="admonition tip">
 <p class="admonition-title">New</p>
 <p>Introduced in 0.33.0</p>
 </div>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>scheduler-k3s:cluster-add [ssh://user@host:port]    # Adds a server node to a Dokku-managed cluster
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>scheduler-k3s:cluster-list                          # Lists all nodes in a Dokku-managed cluster
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>scheduler-k3s:cluster-remove [node-id]              # Removes client node to a Dokku-managed cluster
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>scheduler-k3s:initialize                            # Initializes a cluster
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>scheduler-k3s:report [&lt;app&gt;] [&lt;flag&gt;]               # Displays a scheduler-k3s report for one or more apps
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>scheduler-k3s:set [&lt;app&gt;|--global] &lt;key&gt; (&lt;value&gt;)  # Set or clear a scheduler-k3s property for an app or the scheduler
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>scheduler-k3s:show-kubeconfig                       # Displays the kubeconfig for remote usage
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>scheduler-k3s:uninstall                             # Uninstalls k3s from the Dokku server
+</code></pre></div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The k3s plugin replaces the external <a href="https://github.com/dokku/dokku-scheduler-kubernetes">scheduler-kubernetes</a> plugin. Users can continue to use the external plugin as necessary, but all future development will occur on the official core k3s plugin.</p>
+</div>
 <p>For multi-server support, Dokku provides the ability for users to setup a K3s cluster. As with all schedulers, it is set on a per-app basis. The scheduler can currently be overridden by running the following command:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>dokku<span class="w"> </span>scheduler:set<span class="w"> </span>node-js-app<span class="w"> </span>selected<span class="w"> </span>k3s
 </code></pre></div>
@@ -3976,6 +4281,44 @@ <h4 id="resource-reservations">Resource Reservations<a class="headerlink" href="
         <footer class="md-footer">
   
     
+      
+      <nav class="md-footer__inner md-grid" aria-label="Footer" >
+        
+          
+          <a href="../docker-local/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Docker Local Scheduler">
+            <div class="md-footer__button md-icon">
+              
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
+            </div>
+            <div class="md-footer__title">
+              <span class="md-footer__direction">
+                Previous
+              </span>
+              <div class="md-ellipsis">
+                Docker Local Scheduler
+              </div>
+            </div>
+          </a>
+        
+        
+          
+          <a href="../nomad/" class="md-footer__link md-footer__link--next" aria-label="Next: Nomad Scheduler">
+            <div class="md-footer__title">
+              <span class="md-footer__direction">
+                Next
+              </span>
+              <div class="md-ellipsis">
+                Nomad Scheduler
+              </div>
+            </div>
+            <div class="md-footer__button md-icon">
+              
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4Z"/></svg>
+            </div>
+          </a>
+        
+      </nav>
+    
   
   <div class="md-footer-meta md-typeset">
     <div class="md-footer-meta__inner md-grid">
diff --git a/docs/deployment/schedulers/kubernetes/index.html b/docs/deployment/schedulers/kubernetes/index.html
index 830ffb200..2fdd0d401 100644
--- a/docs/deployment/schedulers/kubernetes/index.html
+++ b/docs/deployment/schedulers/kubernetes/index.html
@@ -30,10 +30,6 @@
         <link rel="canonical" href="https://dokku.com/docs/deployment/schedulers/kubernetes/">
       
       
-        <link rel="prev" href="../docker-local/">
-      
-      
-        <link rel="next" href="../nomad/">
       
       
       <link rel="icon" href="../../../assets/favicons/favicon-96x96.png">
@@ -268,28 +264,22 @@
         
   
   
-    
-  
   
     
     
       
   
   
-    
-  
   
     
     
       
   
-  
-    
   
   
     
     
-      <li class="md-tabs__item md-tabs__item--active">
+      <li class="md-tabs__item">
         <a href="../../../getting-started/installation/" class="md-tabs__link">
           
   
@@ -425,8 +415,6 @@
       
   
   
-    
-  
   
   
     
@@ -467,12 +455,12 @@
       
       
     
-    <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
+    <li class="md-nav__item md-nav__item--section md-nav__item--nested">
       
         
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
         
           
           <label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="">
@@ -486,7 +474,7 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="true">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_1">
             <span class="md-nav__icon md-icon"></span>
             Docs
@@ -2756,8 +2744,6 @@
                 
   
   
-    
-  
   
   
     
@@ -2780,12 +2766,12 @@
       
       
     
-    <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
+    <li class="md-nav__item md-nav__item--section md-nav__item--nested">
       
         
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1_11" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1_11" >
         
           
           <label class="md-nav__link" for="__nav_1_11" id="__nav_1_11_label" tabindex="">
@@ -2799,7 +2785,7 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_1_11_label" aria-expanded="true">
+        <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_1_11_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_1_11">
             <span class="md-nav__icon md-icon"></span>
             Schedulers
@@ -2852,91 +2838,18 @@
                 
   
   
-    
-  
-  
-  
-    <li class="md-nav__item md-nav__item--active">
-      
-      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
-      
-      
-        
-      
-      
-        <label class="md-nav__link md-nav__link--active" for="__toc">
-          
   
-  <span class="md-ellipsis">
-    Kubernetes Scheduler
-  </span>
   
-
-          <span class="md-nav__icon md-icon"></span>
-        </label>
-      
-      <a href="./" class="md-nav__link md-nav__link--active">
+    <li class="md-nav__item">
+      <a href="../k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
       </a>
-      
-        
-
-<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
-  
-  
-  
-    
-  
-  
-    <label class="md-nav__title" for="__toc">
-      <span class="md-nav__icon md-icon"></span>
-      Table of contents
-    </label>
-    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
-      
-        <li class="md-nav__item">
-  <a href="#scheduler-interface" class="md-nav__link">
-    <span class="md-ellipsis">
-      Scheduler Interface
-    </span>
-  </a>
-  
-    <nav class="md-nav" aria-label="Scheduler Interface">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#implemented-commands-and-triggers" class="md-nav__link">
-    <span class="md-ellipsis">
-      Implemented Commands and Triggers
-    </span>
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#logging-support" class="md-nav__link">
-    <span class="md-ellipsis">
-      Logging support
-    </span>
-  </a>
-  
-</li>
-        
-      </ul>
-    </nav>
-  
-</li>
-      
-    </ul>
-  
-</nav>
-      
     </li>
   
 
@@ -3576,44 +3489,6 @@ <h3 id="logging-support">Logging support<a class="headerlink" href="#logging-sup
         <footer class="md-footer">
   
     
-      
-      <nav class="md-footer__inner md-grid" aria-label="Footer" >
-        
-          
-          <a href="../docker-local/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Docker Local Scheduler">
-            <div class="md-footer__button md-icon">
-              
-              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
-            </div>
-            <div class="md-footer__title">
-              <span class="md-footer__direction">
-                Previous
-              </span>
-              <div class="md-ellipsis">
-                Docker Local Scheduler
-              </div>
-            </div>
-          </a>
-        
-        
-          
-          <a href="../nomad/" class="md-footer__link md-footer__link--next" aria-label="Next: Nomad Scheduler">
-            <div class="md-footer__title">
-              <span class="md-footer__direction">
-                Next
-              </span>
-              <div class="md-ellipsis">
-                Nomad Scheduler
-              </div>
-            </div>
-            <div class="md-footer__button md-icon">
-              
-              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4Z"/></svg>
-            </div>
-          </a>
-        
-      </nav>
-    
   
   <div class="md-footer-meta md-typeset">
     <div class="md-footer-meta__inner md-grid">
diff --git a/docs/deployment/schedulers/nomad/index.html b/docs/deployment/schedulers/nomad/index.html
index 86f60e196..d6f0a8cd7 100644
--- a/docs/deployment/schedulers/nomad/index.html
+++ b/docs/deployment/schedulers/nomad/index.html
@@ -30,7 +30,7 @@
         <link rel="canonical" href="https://dokku.com/docs/deployment/schedulers/nomad/">
       
       
-        <link rel="prev" href="../kubernetes/">
+        <link rel="prev" href="../k3s/">
       
       
         <link rel="next" href="../null/">
@@ -2855,11 +2855,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../kubernetes/" class="md-nav__link">
+      <a href="../k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
@@ -3578,7 +3578,7 @@ <h3 id="logging-support">Logging support<a class="headerlink" href="#logging-sup
       <nav class="md-footer__inner md-grid" aria-label="Footer" >
         
           
-          <a href="../kubernetes/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Kubernetes Scheduler">
+          <a href="../k3s/" class="md-footer__link md-footer__link--prev" aria-label="Previous: K3s Scheduler">
             <div class="md-footer__button md-icon">
               
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
@@ -3588,7 +3588,7 @@ <h3 id="logging-support">Logging support<a class="headerlink" href="#logging-sup
                 Previous
               </span>
               <div class="md-ellipsis">
-                Kubernetes Scheduler
+                K3s Scheduler
               </div>
             </div>
           </a>
diff --git a/docs/deployment/schedulers/null/index.html b/docs/deployment/schedulers/null/index.html
index 00cbb0b47..7ece130e3 100644
--- a/docs/deployment/schedulers/null/index.html
+++ b/docs/deployment/schedulers/null/index.html
@@ -2855,11 +2855,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../kubernetes/" class="md-nav__link">
+      <a href="../k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/schedulers/scheduler-management/index.html b/docs/deployment/schedulers/scheduler-management/index.html
index bd57e1f45..92b990aab 100644
--- a/docs/deployment/schedulers/scheduler-management/index.html
+++ b/docs/deployment/schedulers/scheduler-management/index.html
@@ -2946,11 +2946,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../kubernetes/" class="md-nav__link">
+      <a href="../k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/user-management/index.html b/docs/deployment/user-management/index.html
index 44c205d42..7b0799853 100644
--- a/docs/deployment/user-management/index.html
+++ b/docs/deployment/user-management/index.html
@@ -2955,11 +2955,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/deployment/zero-downtime-deploys/index.html b/docs/deployment/zero-downtime-deploys/index.html
index d7bb776a6..dcd7a6a0a 100644
--- a/docs/deployment/zero-downtime-deploys/index.html
+++ b/docs/deployment/zero-downtime-deploys/index.html
@@ -2970,11 +2970,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../schedulers/kubernetes/" class="md-nav__link">
+      <a href="../schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/development/plugin-creation/index.html b/docs/development/plugin-creation/index.html
index acf696078..6596b5a1e 100644
--- a/docs/development/plugin-creation/index.html
+++ b/docs/development/plugin-creation/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/development/plugin-triggers/index.html b/docs/development/plugin-triggers/index.html
index 6a6471b1d..2e34fa2b0 100644
--- a/docs/development/plugin-triggers/index.html
+++ b/docs/development/plugin-triggers/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/development/release-process/index.html b/docs/development/release-process/index.html
index 75795eca0..fb786009e 100644
--- a/docs/development/release-process/index.html
+++ b/docs/development/release-process/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/development/testing/index.html b/docs/development/testing/index.html
index 1c2ed632d..607ef40c4 100644
--- a/docs/development/testing/index.html
+++ b/docs/development/testing/index.html
@@ -2853,11 +2853,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/enterprise/pro/index.html b/docs/enterprise/pro/index.html
index 2a03e594c..1181e236b 100644
--- a/docs/enterprise/pro/index.html
+++ b/docs/enterprise/pro/index.html
@@ -2922,11 +2922,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/advanced-installation/index.html b/docs/getting-started/advanced-installation/index.html
index 494568323..ae9088ecf 100644
--- a/docs/getting-started/advanced-installation/index.html
+++ b/docs/getting-started/advanced-installation/index.html
@@ -2969,11 +2969,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/install/azure/index.html b/docs/getting-started/install/azure/index.html
index 5a5cb94b2..a9a390c42 100644
--- a/docs/getting-started/install/azure/index.html
+++ b/docs/getting-started/install/azure/index.html
@@ -2867,11 +2867,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/install/debian/index.html b/docs/getting-started/install/debian/index.html
index 621fb3965..eb04ecf8e 100644
--- a/docs/getting-started/install/debian/index.html
+++ b/docs/getting-started/install/debian/index.html
@@ -2921,11 +2921,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/install/digitalocean/index.html b/docs/getting-started/install/digitalocean/index.html
index 1b74ab99b..c63cdf6bb 100644
--- a/docs/getting-started/install/digitalocean/index.html
+++ b/docs/getting-started/install/digitalocean/index.html
@@ -2867,11 +2867,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/install/docker/index.html b/docs/getting-started/install/docker/index.html
index e9e8f36ee..bbad5638c 100644
--- a/docs/getting-started/install/docker/index.html
+++ b/docs/getting-started/install/docker/index.html
@@ -2948,11 +2948,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/install/dreamhost/index.html b/docs/getting-started/install/dreamhost/index.html
index 3ed989ce8..fa157959e 100644
--- a/docs/getting-started/install/dreamhost/index.html
+++ b/docs/getting-started/install/dreamhost/index.html
@@ -2867,11 +2867,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/install/vagrant/index.html b/docs/getting-started/install/vagrant/index.html
index ab84ba725..73eb957da 100644
--- a/docs/getting-started/install/vagrant/index.html
+++ b/docs/getting-started/install/vagrant/index.html
@@ -2867,11 +2867,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/installation/index.html b/docs/getting-started/installation/index.html
index 59d4b3573..27468783b 100644
--- a/docs/getting-started/installation/index.html
+++ b/docs/getting-started/installation/index.html
@@ -2855,11 +2855,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/troubleshooting/index.html b/docs/getting-started/troubleshooting/index.html
index 88e2cde0a..bd80c4a4d 100644
--- a/docs/getting-started/troubleshooting/index.html
+++ b/docs/getting-started/troubleshooting/index.html
@@ -3027,11 +3027,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/uninstalling/index.html b/docs/getting-started/uninstalling/index.html
index 8ff32fc26..cc443953b 100644
--- a/docs/getting-started/uninstalling/index.html
+++ b/docs/getting-started/uninstalling/index.html
@@ -2922,11 +2922,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/upgrading/index.html b/docs/getting-started/upgrading/index.html
index 52c0ecd60..3f2d42ac0 100644
--- a/docs/getting-started/upgrading/index.html
+++ b/docs/getting-started/upgrading/index.html
@@ -2857,11 +2857,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/getting-started/where-to-get-help/index.html b/docs/getting-started/where-to-get-help/index.html
index 4a6ccd306..efd763b6e 100644
--- a/docs/getting-started/where-to-get-help/index.html
+++ b/docs/getting-started/where-to-get-help/index.html
@@ -2979,11 +2979,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/index.html b/docs/index.html
index ef58ae8e3..57e065696 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -2836,11 +2836,11 @@
   
   
     <li class="md-nav__item">
-      <a href="deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/dns/index.html b/docs/networking/dns/index.html
index ead8562cc..261daddd3 100644
--- a/docs/networking/dns/index.html
+++ b/docs/networking/dns/index.html
@@ -2964,11 +2964,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/network/index.html b/docs/networking/network/index.html
index 4a347a77e..03ed53e55 100644
--- a/docs/networking/network/index.html
+++ b/docs/networking/network/index.html
@@ -3042,11 +3042,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/port-management/index.html b/docs/networking/port-management/index.html
index 6fc50492a..68667e196 100644
--- a/docs/networking/port-management/index.html
+++ b/docs/networking/port-management/index.html
@@ -3021,11 +3021,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/proxies/caddy/index.html b/docs/networking/proxies/caddy/index.html
index 5fc60e8b8..d7db05cdb 100644
--- a/docs/networking/proxies/caddy/index.html
+++ b/docs/networking/proxies/caddy/index.html
@@ -3039,11 +3039,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/proxies/haproxy/index.html b/docs/networking/proxies/haproxy/index.html
index 9dce9e273..cebb7d9b5 100644
--- a/docs/networking/proxies/haproxy/index.html
+++ b/docs/networking/proxies/haproxy/index.html
@@ -3030,11 +3030,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/proxies/nginx/index.html b/docs/networking/proxies/nginx/index.html
index 452f2d2b9..e967ec540 100644
--- a/docs/networking/proxies/nginx/index.html
+++ b/docs/networking/proxies/nginx/index.html
@@ -3189,11 +3189,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/proxies/openresty/index.html b/docs/networking/proxies/openresty/index.html
index 67da185a1..2dc5ca215 100644
--- a/docs/networking/proxies/openresty/index.html
+++ b/docs/networking/proxies/openresty/index.html
@@ -3057,11 +3057,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/proxies/traefik/index.html b/docs/networking/proxies/traefik/index.html
index 3f01ec14d..ae366bbfe 100644
--- a/docs/networking/proxies/traefik/index.html
+++ b/docs/networking/proxies/traefik/index.html
@@ -3090,11 +3090,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/networking/proxy-management/index.html b/docs/networking/proxy-management/index.html
index d9da6eb40..3d865c3a3 100644
--- a/docs/networking/proxy-management/index.html
+++ b/docs/networking/proxy-management/index.html
@@ -2988,11 +2988,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/processes/entering-containers/index.html b/docs/processes/entering-containers/index.html
index b0459f7d3..48722d7b5 100644
--- a/docs/processes/entering-containers/index.html
+++ b/docs/processes/entering-containers/index.html
@@ -2904,11 +2904,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/processes/one-off-tasks/index.html b/docs/processes/one-off-tasks/index.html
index e37274a2f..2e1ccd414 100644
--- a/docs/processes/one-off-tasks/index.html
+++ b/docs/processes/one-off-tasks/index.html
@@ -3003,11 +3003,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/processes/process-management/index.html b/docs/processes/process-management/index.html
index a2820a3ba..017dda160 100644
--- a/docs/processes/process-management/index.html
+++ b/docs/processes/process-management/index.html
@@ -3090,11 +3090,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/processes/scheduled-cron-tasks/index.html b/docs/processes/scheduled-cron-tasks/index.html
index 23a08e3d6..da8f9b78c 100644
--- a/docs/processes/scheduled-cron-tasks/index.html
+++ b/docs/processes/scheduled-cron-tasks/index.html
@@ -3021,11 +3021,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../deployment/schedulers/kubernetes/" class="md-nav__link">
+      <a href="../../deployment/schedulers/k3s/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Kubernetes Scheduler
+    K3s Scheduler
   </span>
   
 
diff --git a/docs/search/search_index.json b/docs/search/search_index.json
index b51c81d9d..589d06d2c 100644
--- a/docs/search/search_index.json
+++ b/docs/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"advanced-usage/backup-recovery/","title":"Backup and Recovery","text":"<p>Info</p> <p>The backup plugin was deprecated in 0.4.x, below are backup recommendations for 0.5.x and later.</p> <p>The best plan for disaster recovery is to always keep multiple (remote) copies of your local repo, static assets and periodic database dumps. Backups should be regularly tested for data integrity and completeness.</p>"},{"location":"advanced-usage/backup-recovery/#tldr","title":"TLDR","text":"<p>Warning</p> <p>This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis.</p>"},{"location":"advanced-usage/backup-recovery/#creating-a-backup","title":"Creating a backup","text":"<p>To create a backup, run the following command at a time when not executing any Dokku commands or app deployments:</p> <pre><code>export BACKUP_TIME=$(date +%Y-%m-%d-%H-%M)\nsudo mkdir -p /var/lib/dokku/services\nsudo chown dokku:dokku /var/lib/dokku/services\nmkdir -p /tmp/dokku-backups/\nsudo tar -czvf \"/tmp/dokku-backups/${BACKUP_TIME}.tar.gz\" /home/dokku /var/lib/dokku/config /var/lib/dokku/data /var/lib/dokku/services /var/lib/dokku/plugins\n</code></pre> <p>This will create a point-in-time backup of your entire Dokku installation in the <code>/tmp/dokku-backups</code> directory. This backup may be moved offsite to another location via rsync, sftp, or some other protocol.</p> <p>It is recommended that backups are regularly cleaned from the originating server and tested as necessary.</p>"},{"location":"advanced-usage/backup-recovery/#restoring-a-backup","title":"Restoring a backup","text":"<p>To extract the backup onto another server, copy the backup to the server and extract it using the following command.</p> <pre><code>sudo tar -xzvf path/to/dokku/backup.tar.gz -C /\n</code></pre> <p>At this point, all datastores should be individually started and checked for data integrity. Once this is complete, individual apps can be rebuilt. Please consult the process management documentation for more information on how to rebuild apps.</p>"},{"location":"advanced-usage/backup-recovery/#caveats","title":"Caveats","text":""},{"location":"advanced-usage/backup-recovery/#app-config","title":"App config","text":"<p>Application config is largely held in a small number of places:</p> <ul> <li><code>/var/lib/dokku/config</code>: Properties set and managed by plugins</li> <li><code>/var/lib/dokku/data</code>: Files generated or extracted by various plugins</li> <li><code>/home/dokku</code>: Certain parts of Dokku core store data in this location</li> </ul> <p>Compressing these directories when no Dokku commands are running is enough to ensure a complete backup of the system.</p>"},{"location":"advanced-usage/backup-recovery/#code-repositories","title":"Code Repositories","text":"<p>Because Dokku is git based, rebuilding a deployed app is as easy as pushing from git. You can push to a new server by updating the <code>dokku</code> remote in you local app's repo.</p> <pre><code>git remote rm dokku\ngit remote add dokku dokku@[dokku.me:dokku.me]\ngit push dokku [master]\n</code></pre>"},{"location":"advanced-usage/backup-recovery/#docker-networks","title":"Docker Networks","text":"<p>Docker networks generated by Dokku should be recreated. Running <code>dokku network:report</code> will output all networks in use by various apps, which can then be used to recreate them via <code>dokku network:create $NETWORK</code>.</p> <p>Networks created by tools other than Dokku may be created as they initially were.</p>"},{"location":"advanced-usage/backup-recovery/#docker-image-and-tar-based-apps","title":"Docker Image and Tar-based Apps","text":"<p>These apps may fail to rebuild via the normal <code>ps:rebuild</code> method. Redeploy these apps by running the original commands used to deploy them</p>"},{"location":"advanced-usage/backup-recovery/#datastores","title":"Datastores","text":"<p>Info</p> <p>Please note that point-in-time backups of the <code>/var/lib/dokku/services</code> directory may contain partially written data due to how various datastores work. Consult the official datastore documentation for the best documentation surrounding proper backup and restore procedures.</p> <p>Some plugins, like the official dokku-postgres plugin, have built-in commands that allow non-volatile data be exported and imported.</p> <p>For dokku-postgres, use:</p> <pre><code>dokku postgres:export [db_name] &gt; [db_name].dump\ndokku postgres:import [db_name] &lt; [db_name].dump\n</code></pre> <p>Additionally, data for official datastores is located in the <code>/var/lib/dokku/services</code> directory. If the directory is restored and the plugin is available, a <code>dokku $SERVICE:start</code> may be enough to restart the service with the underlying data, so long as the datastore version does not change and the underlying data is not corrupt. If this is the case, it may be necessary to re-import all the data onto a fresh version of the datastore service.</p>"},{"location":"advanced-usage/backup-recovery/#plugins","title":"Plugins","text":"<p>The plugin directory is contained at the <code>/var/lib/dokku/plugins</code> directory. Core plugins will automatically be included in new installs, but custom plugins may not. The aforementioned <code>tar</code> creation command will back all plugins up, and the <code>tar</code> extract command will restore the plugins.</p> <p>Note that restoring a plugin will not trigger any <code>install</code> or <code>dependencies</code> triggers. You will need to run these manually. See the plugin management documentation for more information on how to trigger these two hooks.</p>"},{"location":"advanced-usage/backup-recovery/#volumes-and-static-assets","title":"Volumes and Static Assets","text":"<p>Dokku doesn't enforce a 300mb limit on apps, but it's best practice to keep binary assets outside of git. Since containers are considered volatile in Dokku, external stores like s3 or storage mounts should be used for non-volatile items like user uploads. The Dokku storage core plugin can be used to mount local directories / volumes inside the docker container.</p> <p>System administrators are highly encouraged to store persistent data in app-specific subdirectories of the path <code>/var/lib/dokku/data/storage</code>. This will help ensure restores of the aforementioned primary Dokku directories will restore service to all apps.</p> <p>See the persistent storage documentation for more information on how to attach persistent storage to your app.</p>"},{"location":"advanced-usage/backup-recovery/#recovering-app-code","title":"Recovering app code","text":"<p>In case of an emergency when your git repo and backups are completely lost, you can recover the last pushed copy from your remote Dokku server (assuming you still have the ssh key).</p> <pre><code>mkdir [app-name] ; cd !$\ngit init &amp;&amp; git remote add dokku dokku@[dokku.me:app-name]\ngit pull dokku/master &amp;&amp; git checkout dokku/master\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/","title":"Deployment Tasks","text":"<p>New</p> <p>Introduced in 0.5.0</p>"},{"location":"advanced-usage/deployment-tasks/#usage","title":"Usage","text":""},{"location":"advanced-usage/deployment-tasks/#overview","title":"Overview","text":"<p>Sometimes you need to run a command on deployment time, but before an app is completely deployed. Common use cases include:</p> <ul> <li>Checking a database is initialized</li> <li>Running database migrations</li> <li>Any commands required to set up the server (e.g. something like a Django <code>collectstatic</code>)</li> </ul> <p>To support this, Dokku provides support for a special <code>release</code> command within your app's <code>Procfile</code>, as well as a special <code>scripts.dokku</code> key inside of your app's <code>app.json</code> file. Be aware that all commands are run within the context of the built docker image - no commands affect the host unless there are volume mounts attached to your app.</p> <p>Each \"phase\" has different expectations and limitations:</p> <ul> <li><code>app.json</code>: <code>scripts.dokku.predeploy</code><ul> <li>When to use: This should be used if your app does not support arbitrary build commands and you need to make changes to the built image.</li> <li>Are changes committed to the image at this phase: Yes</li> <li>Example use-cases<ul> <li>Bundling assets in a slightly different way</li> <li>Installing a custom package from source or copying a binary into place</li> </ul> </li> </ul> </li> <li><code>app.json</code>: <code>scripts.dokku.postdeploy</code><ul> <li>When to use: This should be used in conjunction with external systems to signal the completion of your deploy.</li> <li>Are changes committed to the image at this phase: No</li> <li>Example use-cases<ul> <li>Notifying slack that your app is deployed</li> <li>Coordinating traffic routing with a central load balancer</li> </ul> </li> </ul> </li> <li><code>app.json</code>: <code>scripts.postdeploy</code><ul> <li>When to use: This should be used when you wish to run a command once, after the app is created and not on subsequent deploys to the app.</li> <li>Are changes committed to the image at this phase: No</li> <li>Example use-cases<ul> <li>Setting up OAuth clients and DNS</li> <li>Loading seed/test data into the app\u2019s test database</li> </ul> </li> </ul> </li> <li><code>Procfile</code>: <code>release</code><ul> <li>When to use: This should be used in conjunction with external systems to signal the completion of your app image build.</li> <li>Are changes committed to the image at this phase: No</li> <li>Example use-cases<ul> <li>Sending CSS, JS, and other assets from your app\u2019s slug to a CDN or S3 bucket</li> <li>Priming or invalidating cache stores</li> <li>Running database migrations</li> </ul> </li> </ul> </li> </ul> <p>Additionally, if using a Dockerfile with an <code>ENTRYPOINT</code>, the deployment task is passed to that entrypoint as is. The exceptions are if the entrypoint is one of the following:</p> <ul> <li><code>[\"/tini\", \"--\"]</code></li> <li><code>[\"/bin/tini\", \"--\"]</code></li> <li><code>[\"/usr/bin/tini\", \"--\"]</code></li> <li><code>[\"/usr/local/bin/tini\", \"--\"]</code></li> </ul> <p>Please keep the above in mind when utilizing deployment tasks.</p> <p>Info</p> <p>To execute commands on the host during a release phase, see the plugin creation documentation docs for more information on building your own custom plugin.</p>"},{"location":"advanced-usage/deployment-tasks/#changing-the-appjson-location","title":"Changing the <code>app.json</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>app.json</code> file to use for a given app. This can be done via the <code>app-json:set</code> command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no <code>app.json</code> file.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>app.json</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>app.json</code> extracted directly from the source code. Both cases will respect the configured <code>appjson-path</code> property value.</p> <pre><code>dokku app-json:set node-js-app appjson-path .dokku/app.json\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku app-json:set node-js-app appjson-path\n</code></pre> <p>The <code>appjson-path</code> property can also be set globally. The global default is <code>app.json</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku app-json:set --global appjson-path global-app.json\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku app-json:set --global appjson-path\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/#displaying-app-json-reports-for-an-app","title":"Displaying app-json reports for an app","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>You can get a report about the app's storage status using the <code>app-json:report</code> command:</p> ShellOutput <pre><code>dokku app-json:report\n</code></pre> <pre><code>=====&gt; node-js-app app-json information\n       App-json computed appjson path: app2.json\n       App-json global appjson path:   app.json\n       App-json appjson path:          app2.json\n=====&gt; python-sample app-json information\n       App-json computed appjson path: app.json\n       App-json global appjson path:   app.json\n       App-json appjson path:\n=====&gt; ruby-sample app-json information\n       App-json computed appjson path: app.json\n       App-json global appjson path:   app.json\n       App-json appjson path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku app-json:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app app-json information\n       App-json computed appjson path: app2.json\n       App-json global appjson path:   app.json\n       App-json appjson path:          app2.json\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku app-json:report node-js-app --app-json-appjson-path\n</code></pre> <pre><code>app2.json\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/#deployment-tasks_1","title":"Deployment tasks","text":""},{"location":"advanced-usage/deployment-tasks/#appjson-deployment-tasks","title":"<code>app.json</code> deployment tasks","text":"<p>Dokku provides limited support for the <code>app.json</code> manifest from Heroku (documentation available here). The keys available for use with Deployment Tasks are:</p> <ul> <li><code>scripts.dokku.predeploy</code>: This is run after an app's docker image is built, but before any containers are scheduled. Changes made to your image are committed at this phase.</li> <li><code>scripts.dokku.postdeploy</code>: This is run after an app's containers are scheduled. Changes made to your image are not committed at this phase.</li> <li><code>scripts.postdeploy</code>: This is run after an app's containers are scheduled. Changes made to your image are not committed at this phase.</li> </ul> <p>Warning</p> <p>Any failed <code>app.json</code> deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers.</p> <p>The following is an example <code>app.json</code> file. Please note that only the <code>scripts.dokku.predeploy</code> and <code>scripts.dokku.postdeploy</code> tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted.</p> <pre><code>{\n  \"scripts\": {\n    \"dokku\": {\n      \"predeploy\": \"touch /app/predeploy.test\",\n      \"postdeploy\": \"curl https://some.external.api.service.com/deployment?state=success\"\n    },\n    \"postdeploy\": \"curl https://some.external.api.service.com/created?state=success\"\n  }\n}\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/#procfile-release-command","title":"Procfile Release command","text":"<p>New</p> <p>Introduced in 0.14.0</p> <p>The <code>Procfile</code> also supports a special <code>release</code> command which acts in a similar way to the Heroku Release Phase. This command is executed after an app's docker image is built, but before any containers are scheduled. This is also run after any command executed by <code>scripts.dokku.predeploy</code>.</p> <p>To use the <code>release</code> command, simply add a <code>release</code> stanza to your Procfile.</p> <pre><code>release: curl https://some.external.api.service.com/deployment?state=built\n</code></pre> <p>Unlike the <code>scripts.dokku.predeploy</code> command, changes made during by the <code>release</code> command are not persisted to disk.</p>"},{"location":"advanced-usage/docker-options/","title":"Docker Container Options","text":"<p>New</p> <p>Introduced in 0.3.17</p> <p>Pass container options to the <code>docker run</code> command  during Dokku's <code>build</code>, <code>deploy</code> and <code>run</code> phases</p> <pre><code>docker-options:add &lt;app&gt; &lt;phase(s)&gt; OPTION    # Add Docker option to app for phase (comma-separated phase list)\ndocker-options:clear &lt;app&gt; [&lt;phase(s)&gt;...]    # Clear a docker options from application\ndocker-options:remove &lt;app&gt; &lt;phase(s)&gt; OPTION # Remove Docker option from app for phase (comma-separated phase list)\ndocker-options:report [&lt;app&gt;] [&lt;flag&gt;]        # Displays a docker options report for one or more apps\n</code></pre> <p>Info</p> <p>When specifying multiple phases, they must be comma-separated without spaces in between each phase, like so:</p> <pre><code>dokku docker-options:add node-js-app deploy,run \"-v /var/log/node-js-app:/app/logs\"\n</code></pre>"},{"location":"advanced-usage/docker-options/#about-dokku-phases","title":"About Dokku phases","text":"<p>Dokku deploys your application in multiple \"phases\" and the <code>docker-options</code> plugin allows you to pass arguments to their underlying docker container:</p> <ul> <li><code>build</code>: the container that executes the appropriate buildpack</li> <li><code>deploy</code>: the container that executes your running/deployed application</li> <li><code>run</code>: the container that executes any arbitrary command via <code>dokku run</code></li> </ul> <p>Manipulation of docker options will not restart running containers. This enables multiple options to be set/unset before final application. As such, changing an app's docker options must be followed by a <code>dokku ps:rebuild</code> in order to take effect.</p> <p>More information on supported Docker options can be found here.</p> <p>Container options configured via the <code>docker-options</code> plugin are not used to modify the process a container runs. Container options are the <code>[OPTIONS]</code> portion of the following, where <code>[CONTAINER_COMMAND]</code> and <code>[ARG]</code> are the process and the arguments passed to it that are launched in the created container: <code>docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]</code>. Please see the documentation for customizing the run command or use a Procfile to modify the command used by a Dockerfile-based container.</p>"},{"location":"advanced-usage/docker-options/#examples","title":"Examples","text":""},{"location":"advanced-usage/docker-options/#add-docker-options","title":"Add Docker options","text":"<p>Add some options for the deployed/running app and when executing <code>dokku run</code>:</p> <pre><code># Mount a host volume in a Docker container: \"-v /host/path:/container/path\"\ndokku docker-options:add node-js-app deploy \"-v /var/log/node-js-app:/app/logs\"\ndokku docker-options:add node-js-app run \"-v /var/log/node-js-app:/app/logs\"\n</code></pre> <p>Note</p> <p>When mounting a host directory in a Dokku app you should first create that directory as user <code>dokku</code> and then mount the directory under <code>/app</code> in the container using <code>docker-options</code> as above. Otherwise the app will lack write permission in the directory.</p>"},{"location":"advanced-usage/docker-options/#remove-a-docker-option","title":"Remove a Docker option","text":"<pre><code>dokku docker-options:remove node-js-app run \"-v /var/log/node-js-app:/app/logs\"\n</code></pre>"},{"location":"advanced-usage/docker-options/#clear-all-docker-options-for-an-app","title":"Clear all Docker options for an app","text":"<p>Docker options can be removed for a specific app using the <code>docker-options:clear</code> command.</p> ShellOutput <pre><code>dokku docker-options:clear node-js-app\n</code></pre> <pre><code>-----&gt; Clearing docker-options for node-js-app on all phases\n</code></pre> <p>One or more valid phases can also be specified. Phases are comma delimited, and specifying an invalid phase will result in an error.</p> ShellOutputShellOutput <pre><code>dokku docker-options:clear node-js-app run\n</code></pre> <pre><code>-----&gt; Clearing docker-options for node-js-app on phase run\n</code></pre> <pre><code>dokku docker-options:clear node-js-app build,run\n</code></pre> <pre><code>-----&gt; Clearing docker-options for node-js-app on phase build\n-----&gt; Clearing docker-options for node-js-app on phase run\n</code></pre>"},{"location":"advanced-usage/docker-options/#displaying-docker-options-reports-for-an-app","title":"Displaying docker-options reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's docker-options status using the <code>docker-options:report</code> command:</p> ShellOutput <pre><code>dokku docker-options:report\n</code></pre> <pre><code>=====&gt; node-js-app docker options information\n       Docker options build:\n       Docker options deploy: -v /var/log/node-js-app:/app/logs\n       Docker options run:  -v /var/log/node-js-app:/app/logs\n=====&gt; python-sample docker options information\n       Docker options build:\n       Docker options deploy:\n       Docker options run:\n=====&gt; ruby-sample docker options information\n       Docker options build:\n       Docker options deploy:\n       Docker options run:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku docker-options:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app docker options information\n       Docker options build:\n       Docker options deploy: -v /var/log/node-js-app:/app/logs\n       Docker options run:  -v /var/log/node-js-app:/app/logs\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku docker-options:report node-js-app --docker-options-build\n</code></pre>"},{"location":"advanced-usage/event-logs/","title":"Dokku Event Logs","text":"<p>New</p> <p>Introduced in 0.3.21</p> <p>Docker provides an events command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones.</p> <pre><code>events [-t]                              # Show the last events (-t follows)\nevents:list                              # List logged events\nevents:on                                # Enable events logger\nevents:off                               # Disable events logger\n</code></pre>"},{"location":"advanced-usage/event-logs/#usage","title":"Usage","text":"<p>Enable the plugin:</p> ShellOutput <pre><code>dokku events:on\n</code></pre> <pre><code>Enabling dokku events logger\n</code></pre> <p>Dokku will then write log entries to <code>/var/log/syslog</code> as well as a Dokku-specific logs sub-directory <code>/var/log/dokku/events.log</code>, which can be easily displayed with the command <code>dokku events</code>:</p> ShellOutput <pre><code>dokku events\n</code></pre> <pre><code>Jul  3 16:09:48 dokku.me dokku[127630]: INVOKED: pre-release-buildpack( pythonapp )\nJul  3 16:10:02 dokku.me dokku[128095]: INVOKED: docker-args-run( rubyapp )\nJul  3 16:10:02 dokku.me dokku[128114]: INVOKED: docker-args-run( nhl )\nJul  3 16:10:03 dokku.me dokku[128195]: INVOKED: pre-deploy( pythonapp )\nJul  3 16:10:23 dokku.me dokku[129253]: INVOKED: docker-args-deploy( pythonapp )\nJul  3 16:10:24 dokku.me dokku[129451]: INVOKED: check-deploy( pythonapp 6274ced0d4be11af4490cd18abaf77cdd593f025133f403d984e80d86a39acec web 5000 10.0.16.80 )\nJul  3 16:10:35 dokku.me dokku[129561]: INVOKED: docker-args-deploy( pythonapp )\nJul  3 16:10:36 dokku.me dokku[129760]: INVOKED: check-deploy( pythonapp ac88a56ee4161ff37e4b92d1498c3eadc91f0aa7c8b81b44fc077e2a51d54cc0 worker )\nJul  3 16:10:46 dokku.me dokku[129851]: INVOKED: post-deploy( pythonapp )\nJul  3 16:10:46 dokku.me dokku[129945]: INVOKED: nginx-pre-reload( pythonapp )\nJul  3 16:15:02 dokku.me dokku[130397]: INVOKED: docker-args-run( goapp )\nJul  3 16:21:02 dokku.me dokku[130796]: INVOKED: docker-args-run( rubyapp )\nJul  3 16:30:02 dokku.me dokku[131384]: INVOKED: docker-args-run( rubyapp )\n</code></pre> <p>You can list all events that are currently being recorded via <code>dokku events:list</code>:</p> ShellOutput <pre><code>dokku events:list\n</code></pre> <pre><code>=====&gt; Events currently logged\ncheck-deploy\ndependencies\ndocker-args-build\ndocker-args-deploy\ndocker-args-run\ngit-post-pull\ngit-pre-pull\nnginx-hostname\nnginx-pre-reload\npost-build-buildpack\npost-build-dockerfile\npost-delete\npost-deploy\npost-domains-update\npre-build-buildpack\npre-build-dockerfile\npre-delete\npre-deploy\npre-release-buildpack\npre-release-dockerfile\nreceive-app\nupdate\n</code></pre>"},{"location":"advanced-usage/persistent-storage/","title":"Persistent Storage","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>The preferred method to mount external containers to a Dokku managed container, is to use the Dokku storage plugin.</p> <pre><code>storage:ensure-directory [--chown option] &lt;directory&gt;  # Creates a persistent storage directory in the recommended storage path\nstorage:list &lt;app&gt; [--format text|json]                # List bind mounts for app's container(s) (host:container)\nstorage:mount &lt;app&gt; &lt;host-dir:container-dir&gt;           # Create a new bind mount\nstorage:report [&lt;app&gt;] [&lt;flag&gt;]                        # Displays a checks report for one or more apps\nstorage:unmount &lt;app&gt; &lt;host-dir:container-dir&gt;         # Remove an existing bind mount\n</code></pre> <p>Info</p> <p>The storage plugin is compatible with storage mounts created with the docker-options. The storage plugin will only list mounts from the deploy/run phase.</p> <p>The storage plugin supports the following mount points:</p> <ul> <li>explicit paths that exist on the host</li> <li>docker volumes</li> </ul>"},{"location":"advanced-usage/persistent-storage/#usage","title":"Usage","text":""},{"location":"advanced-usage/persistent-storage/#listing-persistent-storage","title":"Listing persistent storage","text":"<p>Persistent storage bind mounts are specified on a per-app basis, and can be listed with the <code>storage:list</code> command:</p> ShellOutput <pre><code>dokku storage:list node-js-app\n</code></pre> <pre><code>-----&gt; node-js-app volume bind-mounts:\n       /var/lib/dokku/data/storage/node-js-app:/app/storage\n</code></pre> <p>The output format can also be set to <code>json</code> for programmatic access:</p> ShellOutput <pre><code>dokku storage:list node-js-app --format json\n</code></pre> <pre><code>[\n  {\n    \"host_path\": \"/var/lib/dokku/data/storage/node-js-app\",\n    \"container_path\": \"/app/storage\",\n    \"volume_options\": \"\"\n  }\n]\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#creating-storage-directories","title":"Creating storage directories","text":"<p>New</p> <p>Introduced in 0.25.5</p> <p>A storage directory can be created with the <code>storage:ensure-directory</code> command. This command will create a subdirectory in the recommended <code>/var/lib/dokku/data/storage</code> path - created during Dokku installation - and prepare it for use with an app.</p> ShellOutput <pre><code>dokku storage:ensure-directory node-js-app\n</code></pre> <pre><code>-----&gt; Ensuring /var/lib/dokku/data/storage/node-js-app exists\n       Setting directory ownership to 32767:32767\n       Directory ready for mounting\n</code></pre> <p>By default, permissions are set for usage with Herokuish buildpacks. These permissions can be changed via the <code>--chown</code> option according to the following table:</p> <ul> <li><code>--chown herokuish</code> (default): Use <code>32767:32767</code> as the folder permissions.<ul> <li>This is used for apps deployed with Buildpacks via Herokuish.</li> </ul> </li> <li><code>--chown heroku</code>: Use <code>1000:1000</code> as the folder permissions.<ul> <li>This is used for apps deployed with Cloud Native Buildpacks using the <code>heroku/builder</code> builder.</li> </ul> </li> <li><code>--chown packeto</code>: Use <code>2000:2000</code> as the folder permissions.<ul> <li>This is used for apps deployed with Cloud Native Buildpacks using the <code>cloudfoundry/cnb</code> or <code>packeto</code> builders.</li> </ul> </li> <li><code>--chown root</code>: Use <code>0:0</code> as the folder permissions.<ul> <li>This is used for containers that run their processes as root, as is typical for most Dockerfile or Docker image deploys.</li> </ul> </li> <li><code>--chown false</code>: Skips the <code>chown</code> call.</li> </ul> <p>Users deploying via Dockerfile will want to specify <code>--chown false</code> and manually <code>chown</code> the created directory if the user and/or group id  of the runnning process in the deployed container do not correspond to any of the above options.</p> <p>Warning</p> <p>Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory.</p>"},{"location":"advanced-usage/persistent-storage/#mounting-storage-into-apps","title":"Mounting storage into apps","text":"<p>Dokku supports mounting both explicit host paths as well as docker volumes via the <code>storage:mount</code> command. This takes two arguments, an app name and a <code>host-path:container-path</code> or <code>docker-volume:container-path</code> combination.</p> <pre><code># mount the directory into your container's /app/storage directory, relative to the container root (/)\n# explicit host paths _must_ exist prior to usage.\ndokku storage:mount node-js-app /var/lib/dokku/data/storage/node-js-app:/app/storage\n\n# mount the docker volume into your container's /app/storage directory, relative to the container root (/)\n# docker volumes _must_ exist prior to usage.\ndokku storage:mount node-js-app some-docker-volume:/app/storage\n</code></pre> <p>In the first example, Dokku will then mount the shared contents of <code>/var/lib/dokku/data/storage/node-js-app</code> to <code>/app/storage</code> inside the container.  The mount point is not relative to your app's working directory, and is instead relative to the root (<code>/</code>) of the container. Mounts are only available for containers created via <code>run</code> and by the deploy process, and not during the build process. In addition, the host path is never auto-created by either Dokku or Docker, and should be an explicit path, not one relative to the current working directory.</p> <p>Info</p> <p>If the <code>/storage</code> path within the container had pre-existing content, the container files will be over-written. This may be an issue for users that create assets at build time but then mount a directory at the same place during runtime. Files are not merged.</p> <p>Once persistent storage is mounted, the app requires a restart. See the process scaling documentation for more information.</p> <pre><code>dokku ps:restart app-name\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#unmounting-storage","title":"Unmounting storage","text":"<p>If an app no longer requires a mounted volume or directory, the <code>storage:unmount</code> command can be called. This takes the same arguments as the <code>storage:mount</code> command, an app name and a <code>host-path:container-path</code> or <code>docker-volume:container-path</code> combination.</p> <pre><code># unmount the directory from your container's /app/storage directory, relative to the container root (/)\ndokku storage:unmount node-js-app /var/lib/dokku/data/storage/node-js-app:/app/storage\n\n# unmount the docker volume from your container's /app/storage directory, relative to the container root (/)\ndokku storage:unmount node-js-app some-docker-volume:/app/storage\n</code></pre> <p>Once persistent storage is unmounted, the app requires a restart. See the process scaling documentation for more information.</p> <pre><code>dokku ps:restart app-name\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#displaying-storage-reports-for-an-app","title":"Displaying storage reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's storage status using the <code>storage:report</code> command:</p> ShellOutput <pre><code>dokku storage:report\n</code></pre> <pre><code>=====&gt; node-js-app storage information\n       Storage build mounts:\n       Storage deploy mounts: -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n       Storage run mounts:  -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n=====&gt; python-sample storage information\n       Storage build mounts:\n       Storage deploy mounts:\n       Storage run mounts:\n=====&gt; ruby-sample storage information\n       Storage build mounts:\n       Storage deploy mounts:\n       Storage run mounts:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku storage:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app storage information\n       Storage build mounts:\n       Storage deploy mounts: -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n       Storage run mounts:  -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku storage:report node-js-app --storage-deploy-mounts\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#use-cases","title":"Use Cases","text":""},{"location":"advanced-usage/persistent-storage/#sharing-storage-across-deploys","title":"Sharing storage across deploys","text":"<p>Dokku is powered by Docker containers, which recommends in their best practices that containers be treated as ephemeral. In order to manage persistent storage for web apps, like user uploads or large binary assets like images, a directory outside the container should be mounted.</p>"},{"location":"advanced-usage/persistent-storage/#shared-storage-between-containers","title":"Shared storage between containers","text":"<p>When scaling your app, you may require a common location to access shared assets between containers, a storage mount can be used in this situation.</p>"},{"location":"advanced-usage/persistent-storage/#shared-storage-across-environments","title":"Shared storage across environments","text":"<p>Your app may be used in a cluster that requires containers or resources not running on the same host access your data. Mounting a shared file service (like S3FS or EFS) inside your container will give you great flexibility.</p>"},{"location":"advanced-usage/persistent-storage/#backing-up","title":"Backing up","text":"<p>Your app may have services that are running in memory and need to be backed up locally (like a key store). Mount a non ephemeral storage mount will allow backups that are not lost when the app is shut down.</p>"},{"location":"advanced-usage/persistent-storage/#build-phase","title":"Build phase","text":"<p>By default, Dokku will only bind storage mounts during the deploy and run phases. Under certain conditions, one might want to bind a storage mount during the build phase. This can be accomplished by using the <code>docker-options</code> plugin directly.</p> <pre><code>dokku docker-options:add node-js-app build \"-v /tmp/python-test:/opt/test\"\n</code></pre> <p>You cannot use mounted volumes during the build phase of a Dockerfile deploy. This is because Docker does not support volumes when executing <code>docker build</code>.</p> <p>Warning</p> <p>This can cause data loss if you bind a mount under <code>/app</code> in buildpack apps as herokuish will attempt to remove the original app path during the build phase.</p>"},{"location":"advanced-usage/persistent-storage/#app-user-and-persistent-storage-file-ownership-buildpack-apps-only","title":"App User and Persistent Storage file ownership (buildpack apps only)","text":"<p>New</p> <p>Introduced in 0.7.1</p> <p>By default, Dokku will execute your buildpack app processes as the <code>herokuishuser</code> user. You may override this by setting the <code>DOKKU_APP_USER</code> config variable.</p> <p>Note</p> <p>this user must exist in your herokuish image.</p> <p>Additionally, the default <code>docker-local</code> scheduler that comes with Dokku will ensure your storage mounts are owned by either <code>herokuishuser</code> or the overridden value you have set in <code>DOKKU_APP_USER</code>. See the docker-local scheduler documentation docs for more information.</p>"},{"location":"advanced-usage/plugin-management/","title":"Plugin Management","text":"<p>New</p> <p>Introduced in 0.4.0</p> <pre><code>plugin:disable &lt;name&gt;                    # Disable an installed plugin (third-party only)\nplugin:enable &lt;name&gt;                     # Enable a previously disabled plugin\nplugin:install [--core|--git-url] [--committish branch|commit|tag] [--name custom-plugin-name]           # Optionally download git-url (and pin to the specified branch/commit/tag) &amp; run install trigger for active plugins (or only core ones)\nplugin:installed &lt;name&gt;                  # Checks if a plugin is installed\nplugin:install-dependencies [--core]     # Run install-dependencies trigger for active plugins (or only core ones)\nplugin:list                              # Print active plugins\nplugin:trigger &lt;args...&gt;.                # Trigger an arbitrary plugin hook\nplugin:uninstall &lt;name&gt;                  # Uninstall a plugin (third-party only)\nplugin:update [name [branch|commit|tag]] # Optionally update named plugin from git (and pin to the specified branch/commit/tag) &amp; run update trigger for active plugins\n</code></pre> <pre><code># for 0.3.x\ncd /var/lib/dokku/plugins\ngit clone &lt;git url&gt;\ndokku plugins-install\n</code></pre> <p>Info</p> <p>These commands require <code>root</code> permissions as the <code>install</code> and <code>install-dependencies</code> plugin triggers may utilize commands such as <code>apt-get</code>. For non-core plugins, please inspect those plugins before running the following command as <code>root</code> user.</p>"},{"location":"advanced-usage/plugin-management/#usage","title":"Usage","text":""},{"location":"advanced-usage/plugin-management/#listing-plugins","title":"Listing Plugins","text":"<p>Installed plugins can be listed via the <code>plugin:list</code> command:</p> ShellOutput <pre><code>dokku plugin:list\n</code></pre> <pre><code>plugn: dev\n  00_dokku-standard    0.32.4 enabled    dokku core standard plugin\n  20_events            0.32.4 enabled    dokku core events logging plugin\n  app-json             0.32.4 enabled    dokku core app-json plugin\n  apps                 0.32.4 enabled    dokku core apps plugin\n  build-env            0.32.4 enabled    dokku core build-env plugin\n  buildpacks           0.32.4 enabled    dokku core buildpacks plugin\n  certs                0.32.4 enabled    dokku core certificate management plugin\n  checks               0.32.4 enabled    dokku core checks plugin\n  common               0.32.4 enabled    dokku core common plugin\n  config               0.32.4 enabled    dokku core config plugin\n  docker-options       0.32.4 enabled    dokku core docker-options plugin\n  domains              0.32.4 enabled    dokku core domains plugin\n  enter                0.32.4 enabled    dokku core enter plugin\n  git                  0.32.4 enabled    dokku core git plugin\n  logs                 0.32.4 enabled    dokku core logs plugin\n  network              0.32.4 enabled    dokku core network plugin\n  nginx-vhosts         0.32.4 enabled    dokku core nginx-vhosts plugin\n  plugin               0.32.4 enabled    dokku core plugin plugin\n  proxy                0.32.4 enabled    dokku core proxy plugin\n  ps                   0.32.4 enabled    dokku core ps plugin\n  repo                 0.32.4 enabled    dokku core repo plugin\n  resource             0.32.4 enabled    dokku core resource plugin\n  scheduler-docker-local 0.32.4 enabled    dokku core scheduler-docker-local plugin\n  shell                0.32.4 enabled    dokku core shell plugin\n  ssh-keys             0.32.4 enabled    dokku core ssh-keys plugin\n  storage              0.32.4 enabled    dokku core storage plugin\n  tags                 0.32.4 enabled    dokku core tags plugin\n  tar                  0.32.4 enabled    dokku core tar plugin\n  trace                0.32.4 enabled    dokku core trace plugin\n</code></pre> <p>Warning</p> <p>All plugin commands other than <code>plugin:list</code> and <code>plugin:help</code> require sudo access and must be run directly from the Dokku server.</p>"},{"location":"advanced-usage/plugin-management/#checking-if-a-plugin-is-installed","title":"Checking if a plugin is installed","text":"<p>You can check if a plugin has been installed via the <code>plugin:installed</code> command:</p> <pre><code>dokku plugin:installed postgres\n</code></pre>"},{"location":"advanced-usage/plugin-management/#installing-a-plugin","title":"Installing a plugin","text":"<p>Note</p> <p>Plugins installed in this method within a docker-based installation of Dokku do not persist across installs. Please see the plugin installation section of the docker-based installation docs for further details.</p> <p>Installing a plugin is easy as well using the <code>plugin:install</code> command. This command will also trigger the <code>install</code> pluginhook on all existing plugins.</p> <p>The most common usage is to install a plugin from a url. This url may be any of the following:</p> <ul> <li><code>git</code>: For git+ssh based plugin repository clones.</li> <li><code>ssh</code>: For git+ssh based plugin repository clones.</li> <li><code>file</code>: For copying plugins from a path on disk.</li> <li><code>https</code>: For http based plugin repository clones.</li> </ul> <p>Additionally, any urls with the extensions <code>.tar.gz</code> or <code>.tgz</code> are treated as Gzipped Tarballs for installation purposes and will be downloaded and extracted into place.</p> ShellOutput <pre><code>dokku plugin:install https://github.com/dokku/dokku-postgres.git\n</code></pre> <pre><code>-----&gt; Cloning plugin repo https://github.com/dokku/dokku-postgres.git to /var/lib/dokku/plugins/available/postgres\nCloning into 'postgres'...\nremote: Counting objects: 646, done.\nremote: Total 646 (delta 0), reused 0 (delta 0), pack-reused 646\nReceiving objects: 100% (646/646), 134.24 KiB | 0 bytes/s, done.\nResolving deltas: 100% (406/406), done.\nChecking connectivity... done.\n-----&gt; Plugin postgres enabled\n</code></pre> <p>For git-based plugin installation, a commit SHA-like object may be specified (tag/branch/commit sha) via the <code>--committish</code> argument and Dokku will attempt to install the specified commit object.</p> <pre><code># where 2.0.0 is a potential git tag\ndokku plugin:install https://github.com/dokku/dokku-postgres.git --committish 2.0.0\n</code></pre> <p>Plugin names are interpolated based on the repository name minus the <code>dokku-</code> prefix. If the plugin being installed has a name other than what matches the repository name - or another name is desired - the <code>--name</code> flag can be used to override this interpolation.</p> <pre><code>dokku plugin:install https://github.com/dokku/smoke-test-plugin.git --name smoke-test-plugin\n</code></pre> <p>The <code>--core</code> flag may also be indicated as the sole argument, though it is only for installation of core plugins, and thus not useful for end-user installations.</p> <pre><code>dokku plugin:install --core\n</code></pre> <p>Finally, all flags may be omitted to trigger the <code>install</code> procedures for both core and third-party plugins:</p> <pre><code>dokku plugin:install\n</code></pre>"},{"location":"advanced-usage/plugin-management/#installing-plugin-dependencies","title":"Installing plugin dependencies","text":"<p>In some cases, plugins will have system-level dependencies. These are not automatically installed via <code>plugin:install</code>, and must be separately via the <code>plugin:install-dependencies</code> command. This will run through all the <code>dependencies</code> trigger for all plugins.</p> <pre><code>dokku plugin:install-dependencies\n</code></pre> <p>This command may also target just core plugins via the <code>--core</code> flag. This is usually only useful for source-based installs of Dokku.</p> <pre><code>dokku plugin:install-dependencies --core\n</code></pre>"},{"location":"advanced-usage/plugin-management/#updating-a-plugin","title":"Updating a plugin","text":"<p>An installed, third-party plugin can be updated can updated via the <code>plugin:update</code> command. This should be done after any upgrades of Dokku as there may be changes in the internal api that require an update of how the plugin interfaces with Dokku.</p> <p>Please note that this command is only valid for plugin installs that were backed by a git-repository.</p> ShellOutput <pre><code>dokku plugin:update postgres\n</code></pre> <pre><code>Plugin (postgres) updated\n</code></pre> <p>An optional commit SHA-like object may be specified.</p> <pre><code>dokku plugin:update postgres 2.0.0\n</code></pre> <p>Any future invocation of <code>plugin:update</code> will respect the previously specified SHA-like object. To follow a particular branch again, specify that branch:</p> <pre><code>dokku plugin:update postgres main\n</code></pre>"},{"location":"advanced-usage/plugin-management/#uninstalling-a-plugin","title":"Uninstalling a plugin","text":"<p>Third party plugins can be uninstalled using the <code>plugin:uninstall</code> command:</p> ShellOutput <pre><code>dokku plugin:uninstall postgres\n</code></pre> <pre><code>-----&gt; Plugin postgres uninstalled\n</code></pre>"},{"location":"advanced-usage/plugin-management/#disabling-a-plugin","title":"Disabling a plugin","text":"<p>Disabling a plugin can also be useful for debugging whether a third-party plugin is causing issues in a Dokku installation. Another common use case is for disabling core functionality for replacement with a third-party plugin.</p> ShellOutput <pre><code>dokku plugin:disable postgres\n</code></pre> <pre><code>-----&gt; Plugin postgres disabled\n</code></pre>"},{"location":"advanced-usage/plugin-management/#enabling-a-plugin","title":"Enabling a plugin","text":"<p>Disabled plugins can be re-enabled via the <code>plugin:enable</code> command.</p> ShellOutput <pre><code>dokku plugin:enable postgres\n</code></pre> <pre><code>-----&gt; Plugin postgres enabled\n</code></pre>"},{"location":"advanced-usage/plugin-management/#triggering-a-plugin-trigger","title":"Triggering a plugin trigger","text":"<p>The <code>plugin:trigger</code> can be used to call any internal plugin trigger. This may have unintended consequences, and thus should only be called for development or debugging purposes.</p> <pre><code>dokku plugin:trigger some-internal-trigger args-go-here\n</code></pre>"},{"location":"advanced-usage/registry-management/","title":"Registry Management","text":"<p>New</p> <p>Introduced in 0.25.0</p> <pre><code>registry:login [--password-stdin] &lt;server&gt; &lt;username&gt; [&lt;password&gt;] # Login to a docker registry\nregistry:report [&lt;app&gt;] [&lt;flag&gt;]                                   # Displays a registry report for one or more apps\nregistry:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)                                 # Set or clear a registry property for an app\n</code></pre> <p>The registry plugin enables interacting with remote registries, which is useful when either deploying images via <code>git:from-image</code> or when interacting with custom schedulers to deploy built image artifacts.</p>"},{"location":"advanced-usage/registry-management/#usage","title":"Usage","text":""},{"location":"advanced-usage/registry-management/#logging-into-a-registry","title":"Logging into a registry","text":"<p>The <code>registry:login</code> command can be used to log into a docker registry. The following are examples for logging into various common registries:</p> <pre><code># hub.docker.com\ndokku registry:login docker.io $USERNAME $PASSWORD\n\n# digitalocean\n# the username and password are both defined as the same api token\ndokku registry:login registry.digitalocean.com $DIGITALOCEAN_API_TOKEN $DIGITALOCEAN_API_TOKEN\n\n# github container registry\n# see the following link for information on retrieving a personal access token\n#   https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images#authenticating-to-github-container-registry\ndokku registry:login ghcr.io $USERNAME $REGISTRY_PAT_TOKEN\n\n# quay\n# a robot user may be used to login\ndokku registry:login quay.io $USERNAME $PASSWORD\n</code></pre> <p>For security reasons, the password may also be specified as stdin by specifying the <code>--password-stdin</code> flag. This is supported regardless of the registry being logged into.</p> <pre><code>echo \"$PASSWORD\" | dokku registry:login --password-stdin docker.io $USERNAME\n</code></pre> <p>For certain Docker registries - such as Amazon ECR or Google's GCR registries - users may instead wish to use a docker credential helper to automatically authenticate against a server; please see the documentation regarding the credential helper in question for further setup instructions.</p>"},{"location":"advanced-usage/registry-management/#setting-a-remote-server","title":"Setting a remote server","text":"<p>To specify a remote server registry for pushes, set the <code>server</code> property via the <code>registry:set</code> command. The default value for this property is empty string. Setting the value to <code>docker.io</code> or <code>hub.docker.com</code> will result in the computed value being empty string (as that is the default, implicit registry), while any non-zero length value will have a <code>/</code> appended to it if there is not one already.</p> <pre><code>dokku registry:set node-js-app server docker.io\n</code></pre> <p>This property can be set for a single app or globally via the <code>--global</code> flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is empty string.</p> <pre><code>dokku registry:set --global server docker.io\n</code></pre> <p>Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.</p> <pre><code># per-app\ndokku registry:set node-js-app server\n\n# globally\ndokku registry:set --global server\n</code></pre> <p>The following are the values that should be used for common remote servers:</p> <ul> <li>Amazon Elastic Container Registry:<ul> <li>value: <code>$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/</code></li> <li>notes: The <code>$AWS_ACCOUNT_ID</code> and <code>$AWS_REGION</code> should match the values for your account and region, respectively. Additionally, an IAM profile that allows <code>push</code> access to the repository specified by <code>image-repo</code> should be attached to your Dokku server.</li> </ul> </li> <li>Azure Container Registry:<ul> <li>value <code>$REGISTRY_NAME.azurecr.io/</code></li> <li>notes: The <code>$AKS_REGISTRY_NAME</code> should match the name of the registry created on your account.</li> </ul> </li> <li>Docker Hub:<ul> <li>value: <code>docker.io/</code></li> <li>notes: Requires owning the namespace used in the <code>image-repo</code> value.</li> </ul> </li> <li>Digitalocean:<ul> <li>value: <code>registry.digitalocean.com/</code></li> <li>notes: Requires setting the correct <code>image-repo</code> value for your registry.</li> </ul> </li> <li>Github Container Registry:<ul> <li>value: <code>ghcr.io/</code></li> <li>notes: Requires that the authenticated user has access to the namespace used in the <code>image-repo</code> value.</li> </ul> </li> <li>Quay.io:<ul> <li>value: <code>quay.io/</code></li> </ul> </li> </ul>"},{"location":"advanced-usage/registry-management/#specifying-an-image-repository-name","title":"Specifying an image repository name","text":"<p>By default, Dokku uses the value <code>dokku/$APP_NAME</code> as the image repository that is pushed and deployed. For certain registries, the <code>dokku</code> namespace may not be available to your user. In these cases, the value can be set by changing the value of the <code>image-repo</code> property via the <code>registry:set</code> command.</p> <pre><code>dokku registry:set node-js-app image-repo my-awesome-prefix/node-js-app\n</code></pre> <p>Setting the property value to an empty string will reset the value to the system default. Resetting the value has to be done per-app.</p> <pre><code># per-app\ndokku registry:set node-js-app image-repo\n</code></pre>"},{"location":"advanced-usage/registry-management/#templating-the-image-repository-name","title":"Templating the image repository name","text":"<p>Instead of setting the image repository name on a per-app basis, it can be set via a template globally with the <code>image-repo-template</code> property:</p> <pre><code>dokku registry:set --global image-repo-template \"my-awesome-prefix/{{ .AppName }}\"\n</code></pre> <p>Dokku uses a Golang template and has access to the <code>AppName</code> variable as shown above.</p>"},{"location":"advanced-usage/registry-management/#pushing-images-on-build","title":"Pushing images on build","text":"<p>To push the image on release, set the <code>push-on-release</code> property to <code>true</code> via the <code>registry:set</code> command. The default value for this property is <code>false</code>. Setting the property to <code>true</code> will result in the image being tagged with an ID that is incremented with every release. This tag will be what is used for running app code.</p> <pre><code>dokku registry:set node-js-app push-on-release true\n</code></pre> <p>This property can be set for a single app or globally via the <code>--global</code> flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is <code>false</code>.</p> <pre><code>dokku registry:set --global push-on-release true\n</code></pre> <p>Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.</p> <pre><code># per-app\ndokku registry:set node-js-app push-on-release\n\n# globally\ndokku registry:set --global push-on-release\n</code></pre>"},{"location":"advanced-usage/repository-management/","title":"Repository Management","text":"<p>New</p> <p>Introduced in 0.6.0</p> <pre><code>repo:gc &lt;app&gt;                            # Runs 'git gc --aggressive' against the application's repo\nrepo:purge-cache &lt;app&gt;                   # Deletes the contents of the build cache stored in the repository\n</code></pre> <p>The repository plugin is meant to allow users to perform management commands against a repository.</p>"},{"location":"advanced-usage/repository-management/#usage","title":"Usage","text":""},{"location":"advanced-usage/repository-management/#git-garbage-collection","title":"Git Garbage Collection","text":"<p>This will run a git gc --aggressive against the applications repo. This is performed on the Dokku host, and not within an application container.</p> ShellOutput <pre><code>dokku repo:gc node-js-app\n</code></pre> <pre><code>Counting objects: 396, done.\nDelta compression using up to 2 threads.\nCompressing objects: 100% (365/365), done.\nWriting objects: 100% (396/396), done.\nTotal 396 (delta 79), reused 315 (delta 0)\n</code></pre>"},{"location":"advanced-usage/repository-management/#clearing-application-cache","title":"Clearing Application cache","text":"<p>Building containers with buildpacks currently results in a persistent <code>cache</code> directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command:</p> <pre><code>dokku repo:purge-cache node-js-app\n</code></pre>"},{"location":"advanced-usage/resource-management/","title":"Resource Management","text":"<p>New</p> <p>Introduced in 0.15.0</p> <pre><code>resource:limit [--process-type &lt;process-type&gt;] [RESOURCE_OPTS...] &lt;app&gt;    # Limit resources for a given app/process-type combination\nresource:limit-clear [--process-type &lt;process-type&gt;] &lt;app&gt;                 # Limit resources for a given app/process-type combination\nresource:report [&lt;app&gt;] [&lt;flag&gt;]                                           # Displays a resource report for one or more apps\nresource:reserve [--process-type &lt;process-type&gt;] [RESOURCE_OPTS...] &lt;app&gt;  # Reserve resources for a given app/process-type combination\nresource:reserve-clear [--process-type &lt;process-type&gt;] &lt;app&gt;               # Reserve resources for a given app/process-type combination\n</code></pre> <p>The resource plugin is meant to allow users to limit or reserve resources for a given app/process-type combination.</p>"},{"location":"advanced-usage/resource-management/#usage","title":"Usage","text":"<p>By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The <code>resource</code> plugin allows management of both resource \"limits\" and resource \"reservations\", where each resource request type has specific meaning to the scheduler in use for a given app.</p> <p>Warning</p> <p>The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect.</p> <p>Valid resource options include:</p> <ul> <li><code>--cpu</code></li> <li><code>--memory</code></li> <li><code>--memory-swap</code></li> <li><code>--network</code></li> <li><code>--network-ingress</code></li> <li><code>--network-egress</code></li> <li><code>--nvidia-gpu</code></li> </ul> <p>See the Supported Resource Management Properties section of the docker local scheduler documentation for more information on how each resource limit maps to Docker.</p> <p>Resource limits and reservations are applied only during the <code>run</code> and <code>deploy</code> phases of an application, and will not impact the <code>build</code> phase of an application.</p>"},{"location":"advanced-usage/resource-management/#resource-limits","title":"Resource Limits","text":"<p>When specified and supported, a resource limit will ensure that your app does not go over the specified value. If this occurs, the underlying scheduler may either cap resource utilization, or it may decide to terminate and reschedule your process.</p> <p>Resource limits may be set via the <code>resource:limit</code> command:</p> ShellOutput <pre><code>dokku resource:limit --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app\n       memory: 100\n</code></pre> <p>Multiple resources can be limited in a single call:</p> ShellOutput <pre><code>dokku resource:limit --cpu 100 --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app\n       cpu: 100\n       memory: 100\n</code></pre> <p>Resources can also be limited on a per-process type basis. If specified, this will override any generic limits set for the app.</p> ShellOutput <pre><code>dokku resource:limit --cpu 100 --memory 100 --process-type worker node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app (worker)\n       cpu: 100\n       memory: 100\n</code></pre> <p>A resource value can be individually cleared by setting the value to the special value <code>clear</code>.</p> ShellOutput <pre><code>dokku resource:limit --cpu clear node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app\n       cpu: cleared\n</code></pre>"},{"location":"advanced-usage/resource-management/#displaying-resource-limits","title":"Displaying Resource Limits","text":"<p>Running the <code>resource:limit</code> command without any flags will display the currently configured default app limits.</p> ShellOutput <pre><code>dokku resource:limit node-js-app\n</code></pre> <pre><code>=====&gt; resource limits node-js-app information [defaults]\n       cpu:\n       memory:\n       memory-swap: 100\n       network: 100\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre> <p>This may also be combined with the <code>--process-type</code> flag to see app limits on a process-type level. Note that the displayed values are not merged with the defaults.</p> ShellOutput <pre><code>dokku resource:limit --process-type web node-js-app\n</code></pre> <pre><code>=====&gt; resource limits node-js-app information (web)\n       cpu: 100\n       memory: 100\n       memory-swap:\n       network:\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre>"},{"location":"advanced-usage/resource-management/#clearing-resource-limits","title":"Clearing Resource Limits","text":"<p>In cases where the values are incorrect - or there is no desire to limit resources - resource limits may be cleared using the <code>resource:limit-clear</code> command.</p> ShellOutput <pre><code>dokku resource:limit-clear node-js-app\n</code></pre> <pre><code>-----&gt; Clearing resource limit for node-js-app\n</code></pre> <p>Defaults can also be cleared by leaving the app unspecified.</p> ShellOutput <pre><code>dokku resource:limit-clear\n</code></pre> <pre><code>-----&gt; Clearing default resource limits\n</code></pre>"},{"location":"advanced-usage/resource-management/#resource-reservations","title":"Resource Reservations","text":"<p>When specified and supported, a resource reservation will ensure that your server has at least the specified resources before placing a given app's process. If there a resource exhaustion, future rebuilds and deploys may fail.</p> <p>Resource reservations may be set via the <code>resource:reserve</code> command:</p> ShellOutput <pre><code>dokku resource:reserve --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app\n       memory: 100\n</code></pre> <p>Multiple resources can be limited in a single call:</p> ShellOutput <pre><code>dokku resource:reserve --cpu 100 --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app\n       cpu: 100\n       memory: 100\n</code></pre> <p>Resources can also be limited on a per-process type basis. If specified, this will override any generic limits set for the app.</p> ShellOutput <pre><code>dokku resource:reserve --cpu 100 --memory 100 --process-type worker node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app (worker)\n       cpu: 100\n       memory: 100\n</code></pre> <p>A resource value can be individually cleared by setting the value to the special value <code>clear</code>.</p> ShellOutput <pre><code>dokku resource:reserve --cpu clear node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app\n       cpu: cleared\n</code></pre>"},{"location":"advanced-usage/resource-management/#displaying-resource-reservations","title":"Displaying Resource Reservations","text":"<p>Running the <code>resource:reserve</code> command without any flags will display the currently configured default app reservations.</p> ShellOutput <pre><code>dokku resource:reserve node-js-app\n</code></pre> <pre><code>=====&gt; resource reservation node-js-app information [defaults]\n       cpu: 100\n       memory: 100\n       memory-swap:\n       network:\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre> <p>This may also be combined with the <code>--process-type</code> flag to see app reservations on a process-type level. Note that the displayed values are not merged with the defaults.</p> ShellOutput <pre><code>dokku resource:reserve --process-type web node-js-app\n</code></pre> <pre><code>=====&gt; resource reservation node-js-app information (web)\n       cpu: 100\n       memory: 100\n       memory-swap:\n       network:\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre>"},{"location":"advanced-usage/resource-management/#clearing-resource-reservations","title":"Clearing Resource Reservations","text":"<p>In cases where the values are incorrect - or there is no desire to reserve resources - resource reservations may be cleared using the <code>resource:reserve-clear</code> command.</p> ShellOutput <pre><code>dokku resource:reserve-clear node-js-app\n</code></pre> <pre><code>-----&gt; Clearing resource reservation for node-js-app\n</code></pre> <p>Defaults can also be cleared by leaving the app unspecified.</p> ShellOutput <pre><code>dokku resource:reserve-clear\n</code></pre> <pre><code>-----&gt; Clearing default resource reservation\n</code></pre>"},{"location":"advanced-usage/resource-management/#displaying-resource-reports-for-an-app","title":"Displaying resource reports for an app","text":"<p>You can get a report about the app's resource status using the <code>resource:report</code> command:</p> ShellOutput <pre><code>dokku resource:report\n</code></pre> <pre><code>=====&gt; node-js-app resource information\n       web limit cpu:\n       web limit memory: 1024\n       web limit memory swap: 0\n       web limit network: 10\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory: 512\n       web reservation memory swap:\n       web reservation network: 8\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n=====&gt; python-sample resource information\n       web limit cpu:\n       web limit memory:\n       web limit memory swap:\n       web limit network:\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory:\n       web reservation memory swap:\n       web reservation network:\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n=====&gt; ruby-sample resource information\n       web limit cpu:\n       web limit memory:\n       web limit memory swap:\n       web limit network:\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory:\n       web reservation memory swap:\n       web reservation network:\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku resource:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app resource information\n       web limit cpu:\n       web limit memory: 1024\n       web limit memory swap: 0\n       web limit network: 10\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory: 512\n       web reservation memory swap:\n       web reservation network: 8\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code># Note the periods in the flag name\ndokku resource:report node-js-app --resource-web.limit.memory\n</code></pre> <pre><code>1024\n</code></pre>"},{"location":"appendices/0.10.0-migration-guide/","title":"0.10.0 Migration Guide","text":""},{"location":"appendices/0.10.0-migration-guide/#pci-compliance","title":"PCI Compliance","text":"<p>By default, Dokku will ship a PCI Compliant nginx configuration. For developers whose users are on older browsers or mobile devices, you may need to ship a custom <code>nginx.conf.sigil</code> to enable ciphers for older browsers.</p> <p>See the nginx customization docs for more details.</p>"},{"location":"appendices/0.10.0-migration-guide/#nginx-error-pages","title":"Nginx Error Pages","text":"<p>We now ship with nicer error pages by default. You are free to customize your Dokku installation via a custom <code>nginx.conf.sigil</code> to change what error pages are displayed in different circumstances.</p> <p>See the nginx customization docs for more details.</p>"},{"location":"appendices/0.20.0-migration-guide/","title":"0.20.0 Migration Guide","text":""},{"location":"appendices/0.20.0-migration-guide/#removals","title":"Removals","text":""},{"location":"appendices/0.20.0-migration-guide/#command-removals","title":"Command removals","text":"<p>The following commands were previously deprecated and were removed in this release.</p> <ul> <li><code>apps</code>: Use <code>apps:list</code> instead.</li> <li><code>certs</code>: Use <code>certs:report</code> instead.</li> <li><code>certs:info</code>: Use <code>certs:report</code> instead.</li> <li><code>checks</code>: Use <code>checks:report</code> instead.</li> <li><code>docker-options</code>: Use <code>docker-options:report</code> instead.</li> <li><code>domains</code>: Use <code>domains:report</code> instead.</li> <li><code>plugin</code>: Use <code>plugin:list</code> instead.</li> <li><code>proxy</code>: Use <code>proxy:report</code> instead.</li> <li><code>trace</code>: Use <code>trace:on</code> or <code>trace:off</code> instead.</li> <li><code>ps</code>: Use <code>enter</code> with a container ID instead to run <code>ps auxww</code> within a container.</li> </ul> <p>The refactor of the proxy plugin removes the following functions from being sourced in plugins:</p> <ul> <li><code>proxy#get_app_proxy_port_map()</code></li> <li><code>proxy#list_app_proxy_ports()</code></li> <li><code>proxy#filter_app_proxy_ports()</code></li> <li><code>proxy#add_proxy_ports()</code></li> <li><code>proxy#remove_proxy_ports()</code></li> <li><code>proxy#set_proxy_ports()</code></li> </ul> <p>The informal policy is to allow removal of functions within a <code>functions</code> file if they are not used in OSS plugins. Should you be affected by any such removals, please file an issue to expose the functionality via a plugin trigger.</p>"},{"location":"appendices/0.20.0-migration-guide/#function-renames","title":"Function renames","text":"<ul> <li><code>tar#tar_in_cmd</code> was renamed to <code>tar#cmd-tar-in</code>. Users should avoid using <code>cmd-*</code> commands directly, and instead file an issue to have them exposed via a plugin trigger.</li> <li><code>tar#tar_from_cmd</code> was renamed to <code>tar#cmd-tar-from</code>. Users should avoid using <code>cmd-*</code> commands directly, and instead file an issue to have them exposed via a plugin trigger.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#remove-support-for-unsupported-operating-systems","title":"Remove support for Unsupported Operating Systems","text":"<p>Dokku will no longer distribute packages for Ubuntu versions that have reached either End of Life or End of Standard Support (for LTS releases). This currently includes the following releases:</p> <ul> <li>Ubuntu 14.04 (trusty)</li> <li>Ubuntu 14.10 (utopic)</li> <li>Ubuntu 15.04 (vivid)</li> <li>Ubuntu 15.10 (wily)</li> <li>Ubuntu 16.10 (yakkety)</li> <li>Ubuntu 17.04 (zesty)</li> <li>Ubuntu 17.10 (artful)</li> </ul> <p>Dokku will no longer distribute packages for Debian versions that are not <code>stable</code> or <code>oldstable</code>. This currently includes the following releases:</p> <ul> <li>Debian 7 (wheezy)</li> <li>Debian 8 (jessie)</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#removed-app-report-flags","title":"Removed App report flags","text":"<p>The <code>--git-sha</code> flag was moved from the <code>apps:report</code> command to the <code>git:report</code> command.</p>"},{"location":"appendices/0.20.0-migration-guide/#app-report-output","title":"App report output","text":"<p>When an app is not deployed, the <code>apps:report</code> command no longer shows the message <code>not deployed</code>. Please use the <code>--deployed</code> flag on <code>ps:report</code> instead to see if the app has been deployed.</p>"},{"location":"appendices/0.20.0-migration-guide/#changes","title":"Changes","text":""},{"location":"appendices/0.20.0-migration-guide/#app-report-flags","title":"App report flags","text":"<p>The following changes on the <code>apps:report</code> command were made in this release:</p> <ul> <li>The <code>--deploy-source</code> flag was renamed to <code>--app-deploy-source</code>.</li> <li>The <code>--locked</code> flag was renamed to <code>--app-locked</code>.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#network-report-flags","title":"Network report flags","text":"<p>The following changes on the <code>network:report</code> command were made in this release:</p> <ul> <li>The <code>--network-listeners</code> flag was renamed to <code>--network-web-listeners</code>.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#plugin-triggers","title":"Plugin Triggers","text":"<ul> <li>The <code>network-get-port</code> trigger was incorrectly documented to have the <code>isHerokuishContainer</code> argument as the third argument. The code has been fixed to respect the documentation.</li> <li>The <code>network-get-listeners</code> trigger now takes an additional <code>processType</code> argument. If not specified, it defaults to <code>web</code>. This default will be removed in an upcoming release.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li><code>nginx:show-conf</code> has been deprecated in favor of <code>nginx:show-config</code>.</li> <li><code>proxy#is_app_proxy_enabled()</code> is deprecated in favor of <code>plugn trigger proxy-is-enabled</code>.</li> <li><code>proxy#get_app_proxy_type()</code> is deprecated in favor of <code>plugn trigger proxy-type</code>.</li> <li><code>apps#apps_create()</code> is deprecated in favor of <code>plugn trigger app-create</code>.</li> <li><code>apps#apps_destroy()</code> is deprecated in favor of <code>plugn trigger app-destroy</code>.</li> <li><code>apps#apps_exists()</code> is deprecated in favor of <code>plugn trigger app-exists</code>.</li> <li><code>apps#apps_maybe_create()</code> is deprecated in favor of <code>plugn trigger app-maybe-create</code>.</li> <li><code>plugin trigger network-get-listeners</code> usage without a second <code>processType</code> argument is deprecated.</li> <li><code>.NGINX_PORT</code> variable usage within <code>nginx.conf.sigil</code> templates is deprecated in favor of <code>.PROXY_PORT</code>.</li> <li><code>.NGINX_SSL_PORT</code> variable usage within <code>nginx.conf.sigil</code> templates is deprecated in favor of <code>.PROXY_SSL_PORT</code>.</li> <li><code>.DOKKU_APP_LISTENERS</code> variable usage within <code>nginx.conf.sigil</code> templates is deprecated in favor of <code>.DOKKU_APP_WEB_LISTENERS</code>.</li> </ul>"},{"location":"appendices/0.21.0-migration-guide/","title":"0.21.0 Migration Guide","text":""},{"location":"appendices/0.21.0-migration-guide/#changes","title":"Changes","text":"<p>The <code>tls</code> name is no longer a reserved app name, and can be used by applications. This was previously a reserved app name due to it's use as a place for global SSL certificate files; Dokku has not supported global SSL certificates for many releases, and thus there is no need to reserve the name.</p>"},{"location":"appendices/0.21.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li><code>git#git_deploy_branch()</code> is deprecated in favor of <code>plugn trigger git-deploy-branch</code>.</li> <li>The <code>config</code> command is deprecated in favor of <code>config:show</code>.<ul> <li>Usage of this command in conjunction with either the <code>--export</code> or <code>--shell</code> flag is deprecated in favor of <code>config:export --format</code> with the correct format value (<code>exports</code> or <code>shell</code>, respectively).</li> </ul> </li> <li>The <code>nginx:build-config</code> command is deprecated in favor of <code>proxy:build-config</code>.</li> </ul>"},{"location":"appendices/0.21.0-migration-guide/#removals","title":"Removals","text":"<p>The <code>apps:destroy</code> command no longer takes a second argument <code>force</code>. Instead, this can be passed as the <code>--force</code> flag, either globally or as a flag to the command itself.</p> <p>The <code>proxy:enable</code> and <code>proxy:disable</code> no longer restart apps when setting the <code>DOKKU_DISABLE_PROXY</code> environment variable. A future release will disable usage of <code>DOKKU_DISABLE_PROXY</code> altogether.</p>"},{"location":"appendices/0.22.0-migration-guide/","title":"0.22.0 Migration Guide","text":""},{"location":"appendices/0.22.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>Calling <code>logs:failed</code> without either a <code>&lt;name&gt;</code> or the <code>--all</code> flag is deprecated.</li> </ul>"},{"location":"appendices/0.22.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>Underscores are no longer valid characters in app names. Please rename applications before upgrading.</li> <li>Process type names specified in Procfile may no longer use characters not valid in DNS Label Names (RFC 1123).</li> <li>The minimum Docker version is now 17.05.0.</li> <li>The <code>common.GetDeployingAppImageName()</code> function now returns an <code>error</code> as the second return argument instead of calling <code>common.LogFail()</code> internally.</li> <li>Setting <code>DOKKU_DISABLE_ANSI_PREFIX_REMOVAL</code> is deprecated; Dokku 0.23.0 will avoid removing the <code>remote:</code> ansi prefix entirely. No warning will be added in this release.</li> </ul>"},{"location":"appendices/0.22.0-migration-guide/#removals","title":"Removals","text":"<p>The <code>ps</code> command has had a few removals as a result of a rewrite to Golang:</p> <ul> <li>The <code>ps:set-restart-policy</code> command has been removed in favor the <code>ps:set</code> command.</li> <li>The <code>ps:restart-policy</code> command has been removed in favor of the <code>ps:report</code> command.</li> <li>The <code>ps:rebuildall</code> command has been removed in favor of calling the <code>ps:rebuild</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>ps:restartall</code> command has been removed in favor of calling the <code>ps:restart</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>ps:stopall</code> command has been removed in favor of calling the <code>ps:stop</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>ps:startall</code> command has been removed in favor of calling the <code>ps:start</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>DOKKU_PROCFILE</code> file is no longer located in the git directory for a given app on the server. It's location is currently not exposed.</li> <li>The <code>procfile-get-command</code> plugin trigger no longer takes a <code>procfile path</code> as the final argument.</li> <li>All <code>ps</code> functions have been removed. Please us a trigger as appropriate or file a PR to have a new trigger/wrapper function added.</li> </ul>"},{"location":"appendices/0.23.0-migration-guide/","title":"0.23.0 Migration Guide","text":""},{"location":"appendices/0.23.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The <code>plugin:list</code> command no longer outputs the version for the <code>plugn</code> binary.</li> <li>Users building docker images that run Dokku will need to use a new sudoer wrapper for the <code>docker-image-labeler</code> binary to work correctly. A reference version has been placed in the <code>docker</code> skeleton directory. This should only impact platform developers, and users of our Docker image will already have the file available.</li> <li>The <code>dokku</code> user's cron is now in use by Dokku itself. Customizations will be overwritten. Users are encouraged to use a cron entry in <code>/etc/cron.d/dokku</code> to avoid this issue.</li> <li>As of 0.23.0, Dokku will now inject the <code>max-size</code> log driver option for applications. This is restricted to app-configured log driver values empty, <code>local</code> or <code>json-file</code> in 0.23.1 to increase setup compatibility. Users who configure alternative log drivers at the system level will need to either set the global <code>max-size</code> property to <code>unlimited</code> or switch to the built-in <code>vector</code> logging support.</li> </ul>"},{"location":"appendices/0.24.0-migration-guide/","title":"0.24.0 Migration Guide","text":""},{"location":"appendices/0.24.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The commands <code>proxy:enable</code>, <code>proxy:disable</code> and <code>proxy:build-config</code> now support the <code>--all</code> flag in addition to general parallelism.</li> <li>The <code>builder-cnb</code> plugin has been renamed <code>builder-pack</code>, and all related plugin triggers have had the suffix <code>-cnb</code> changed to <code>-pack</code>.</li> </ul>"},{"location":"appendices/0.24.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>The 1.0.0 release of Dokku will no longer select buildpack builders over dockerfile builders if both builders match. Instead, Dokku will choose the first builder that responds to the <code>builder-detect</code> trigger. Users that wish to use a specific builder may set a builder using the <code>builder:set</code> command, which will force Dokku to use the specified builder regardless of what might be auto-detected.</li> <li>The <code>tags</code> plugin is deprecated in favor of the <code>git:from-image</code> command. It will be removed in the next minor release, and is considered unmaintained. Users are highly encouraged to switch their workflows to <code>git:from-image</code>.</li> <li>The <code>tar</code> plugin is deprecated in favor of the <code>git:from-archive</code> command. It will be removed in the next minor release, and is considered unmaintained. Users are highly encouraged to switch their workflows to <code>git:from-archive</code>.</li> </ul>"},{"location":"appendices/0.25.0-migration-guide/","title":"0.25.0 Migration Guide","text":""},{"location":"appendices/0.25.0-migration-guide/#registry-plugin","title":"Registry Plugin","text":"<p>The dokku-registry plugin is now built-in. This comes with a few changes:</p> <ul> <li>Builder plugins should call <code>post-release-builder</code> at the end of the build.</li> <li>The <code>push</code> and <code>pull</code> command are not implemented. Users wishing to deploy a remote image should use <code>git:from-image</code>. Image pushing is not available at this time.</li> <li>At this time, remote docker repositories are not automatically created for AWS, and users must create those repositories for their applications as necessary. This may be implemented in the future.</li> <li>Docker images are only pushed when configured to do so. See the registry management documentation for more details.</li> </ul> <p>Before upgrading, uninstall the registry plugin via <code>dokku plugin:uninstall registry</code>. Not doing so will cause issues with Dokku.</p>"},{"location":"appendices/0.25.0-migration-guide/#other","title":"Other","text":""},{"location":"appendices/0.25.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The network plugin can now set an <code>initial-network</code> for all containers on creation. This is a replacement for specifying the <code>--network</code> flag via the <code>docker-options</code> plugin. Please see the network documentation for more information.</li> <li>The <code>dokku run</code> command now always removes the ephemeral container on exit. Users that need a persistent container should instead specify a <code>console</code> process type in their <code>Procfile</code> specifying an available shell (usually either <code>bash</code> or <code>sh</code>) and scale that container appropriately.</li> <li>The <code>pre-deploy</code> plugin trigger is now called internally by Dokku. Scheduler plugins should avoid calling this trigger, as any image changes introduced by subsequent trigger calls will be ignored.</li> <li>The default image used for Herokuish Buildpack builds is now <code>gliderlabs/herokuish:latest-20</code>, and is based on both the <code>heroku-20</code> stack as well as Ubuntu 20.04. Users that wish to stick with the old, <code>heroku-18</code>/Ubuntu 18.04 builder may specify <code>gliderlabs/herokuish:latest-18</code> as their builder image. Please see the herokuish buildpack deployment documentation for more information on how to specify a custom buildpack stack builder.<ul> <li>This change does not impact any users of Cloud Native Buildpacks.</li> </ul> </li> <li>We fixed an issue that required extracting Procfiles at the beginning of a deploy. Due to this change, a <code>Dockerfile</code> app contains a <code>Procfile</code> that does not specify a <code>web</code> process will fail to start. Usage of a <code>Procfile</code> with only a <code>release</code> command should be replaced with a <code>scripts.dokku.postdeploy</code> deployment task in the <code>app.json</code> file. The alternative is to define the <code>web</code> process in the <code>Procfile</code>. See the deployment task documentation for more information.</li> </ul>"},{"location":"appendices/0.25.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>In previous versions of Dokku, the only way to specify a custom <code>Dockerfile</code> was to use the <code>docker-options</code> plugin to set the <code>--file</code> flag for a docker build. As of 0.25.0, the <code>builder-dockerfile:set</code> command should be used instead, as outlined in the docs here. Usage of the old method should be migrated to the new method.</li> <li>The <code>--rm</code> and <code>--rm-container</code> flags may be specified but no longer have any effect on <code>dokku run</code>.</li> <li>The <code>--detach</code> flag is deprecated in favor of the <code>run:detached</code> command.</li> <li>The <code>DOKKU_SCALE</code> file is deprecated. Please see the process management documentation for more information on it's replacement with the <code>formation</code> key of the <code>app.json</code> file.</li> <li>The hooks <code>post-release-buildpack</code>, <code>post-release-dockerfile</code>, and <code>post-release-pack</code> are deprecated in favor of <code>post-release-builder</code>. See the plugin triggers documentation for more details.</li> </ul>"},{"location":"appendices/0.25.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>As of April 2021, Ubuntu 16.04 is no longer an LTS release, and support has been removed. Packages may still install on older versions of Ubuntu, but are no longer tested, and therefore no support will be provided.</li> <li>The web installer has been removed. Users are now required to setup Dokku via cli commands. This change was made to combat potential security issues where users ignored the web installer, allowing unauthorized users to add their keys to the host.</li> <li>The <code>scheduler-docker-cleanup</code> plugin trigger has been removed from the scheduler interface, and is no longer invoked.</li> </ul>"},{"location":"appendices/0.26.0-migration-guide/","title":"0.26.0 Migration Guide","text":""},{"location":"appendices/0.26.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>The <code>tags</code> plugin - deprecated in 0.24.0 - was removed. Users are highly encouraged to switch their workflows to <code>git:from-image</code>.</li> <li>The <code>tar</code> plugin - deprecated in 0.24.0 - was removed. Users are highly encouraged to switch their workflows to <code>git:from-archive</code>.</li> </ul>"},{"location":"appendices/0.26.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The <code>scheduler</code> plugin now controls the scheduler in use for deploys. Apps will have their <code>DOKKU_SCHEDULER</code> environment variables migrated to the scheduler plugin, after which that value will be removed from said app. Please see the scheduler documentation for more information.</li> <li>The <code>deploy-source</code> metadata from <code>apps:report</code> is now no longer computed on the fly, but hydrated at deploy time via the <code>deploy-source-set</code> trigger. This value may be empty until your next deploy.<ul> <li>Additionally, the <code>deploy-source</code> trigger has now been removed.</li> </ul> </li> </ul>"},{"location":"appendices/0.27.0-migration-guide/","title":"0.27.0 Migration Guide","text":""},{"location":"appendices/0.27.0-migration-guide/#changes","title":"Changes","text":"<ul> <li> <p>Renaming an application will now only rename domains that are associated with global domains. As an example:</p> <pre><code>dokku domains:set-global dokku.me\ndokku apps:create node-js-app\ndokku domains:set node-js-app node-js-app.dokku.me node-js-app.dokku.com\ndokku apps:rename node-js-app other-name\ndokku domains:report node-js-app --domains-app-vhosts\n# output: other-name.dokku.me node-js-app.dokku.com\n</code></pre> </li> </ul>"},{"location":"appendices/0.28.0-migration-guide/","title":"0.28.0 Migration Guide","text":""},{"location":"appendices/0.28.0-migration-guide/#removals","title":"Removals","text":"<p>Support for the following operating systems has been removed:</p> <ul> <li>CentOS 7</li> <li>Debian 9 (Stretch)</li> <li>Fedora</li> <li>OpenSuse</li> </ul> <p>Dokku will no longer provide packages for RPM based systems. Debian 9 users may use new Debian packages, though support is not guaranteed.</p> <p>All users are encouraged to install Dokku via the Docker-based installation method, or switch to a supported operating system.</p>"},{"location":"appendices/0.28.0-migration-guide/#deprecations","title":"Deprecations","text":"<p>Ubuntu 18.04 is now a deprecated installation target. The operating system will be considered EOL by Canonical in April 2023. Users are encouraged to upgrade to Ubuntu 22.04 or consider switching their instllation method to the Docker-based installation method to avoid any disruption in usage.</p>"},{"location":"appendices/0.28.0-migration-guide/#additions","title":"Additions","text":"<p>New in 0.28.0 are the Caddy, Haproxy and Traefik plugins. As community plugins wrapping these proxies exist, users should:</p> <ul> <li>Recommended: Uninstall the community plugin in question and switch all config to the new plugins.</li> <li>Upgrade the community plugin to a version that does not use the <code>proxy:set</code> value of <code>caddy</code>, <code>haproxy</code> or <code>traefik</code>.</li> </ul>"},{"location":"appendices/0.29.0-migration-guide/","title":"0.29.0 Migration Guide","text":""},{"location":"appendices/0.29.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The output of <code>run:detached</code> now uses the container name - eg. <code>node-js-app.run.1</code> - vs the container id.</li> <li>The ID of <code>cron</code> tasks is now base36-encoded instead of base64-encoded.</li> <li>The <code>nginx.conf.sigil</code> is now extracted when source code is extracted for a build and not from the built image. Users can specify alternative paths via the <code>nginx-conf-sigil-path</code> property of the <code>nginx</code> plugin. See the nginx documentation for more information on how to configure the <code>nginx.conf.sigil</code> path for your application.<ul> <li>For deploys via <code>git:from-image</code>, the <code>nginx.conf.sigil</code> file will be extracted from the source image, respecting the value of <code>nginx-conf-sigil-path</code>.</li> </ul> </li> <li>The <code>Procfile</code> is now extracted when source code is extracted for a build and not from the built image. Users can specify alternative paths via the <code>procfile-path</code> property of the <code>ps</code> plugin. See the process management documentation for more information on how to configure the <code>Procfile</code> path for your application.<ul> <li>For deploys via <code>git:from-image</code>, the <code>Procfile</code> file will be extracted from the source image, respecting the value of <code>procfile-path</code>.</li> </ul> </li> <li>The existing <code>pre-restore</code> hook has been renamed to <code>scheduler-pre-restore</code>. There is a new <code>pre-restore</code> hook that is triggered within the <code>ps:restore</code> command prior to restoring any apps.</li> <li>Nginx init commands are now performed via systemctl on Ubuntu systems when <code>/usr/bin/systemctl</code> is available.</li> </ul>"},{"location":"appendices/0.29.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>The <code>DOKKU_WAIT_TO_RETIRE</code> environment variable has been migrated to a <code>checks</code> property named <code>wait-to-retire</code> and will be ignored if set as an environment variable.</li> <li>The <code>domains-setup</code> trigger has been removed. Initial app domains will now be automatically setup during app creation.</li> <li>The <code>URLS</code> file containing generated urls for an app is no longer generated or referenced. Users should retrieve app urls via the new <code>domains-urls</code> plugin trigger.</li> <li>The common function <code>get_app_urls</code> has been removed. Users should retrieve app urls via the new <code>domains-urls</code> plugin trigger.</li> </ul>"},{"location":"appendices/0.30.0-migration-guide/","title":"0.30.0 Migration Guide","text":"<p>Info</p> <p>Important: Due to the removal of <code>DOKKU_SCALE</code> support, users with a version older than 0.25.x are heavily encouraged to upgrade to 0.29.x prior to 0.30.x. Not doing so will result in all app containers stopping on rebuild due to having no scale settings.</p>"},{"location":"appendices/0.30.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>Support for Ubuntu 18.04 has been deprecated. Please upgrade your host OS in advance of the End Of Life in April 2023.</li> </ul>"},{"location":"appendices/0.30.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The <code>app.json</code> file is now extracted from the source code instead of the built image. For deploys via <code>git:from-image</code>, the file is extracted from the built image.</li> </ul>"},{"location":"appendices/0.30.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>Support for SPDY has been removed. No major browser supports it as of 2021. Custom <code>nginx.conf.sigil</code> templates referencing spdy-related variables will continue to build until the 1.0.0 release.</li> <li>Support for the <code>DOKKU_SCALE</code> file - deprecated in 0.25.0 - has been removed in favor of the <code>formation</code> key in the <code>app.json</code> file. Please see the process management documentation for more information on how to use the <code>formation</code> key of the <code>app.json</code> file.</li> <li>The deprecated <code>--detach</code> global flag for <code>dokku run</code> was removed. Please see the one-off tasks documentation for more information on running detached containers.</li> <li>The following deprecated trigger have been removed in favor of the <code>post-release-builder</code> trigger. See the plugin triggers documentation for more details.<ul> <li><code>post-release-buildpack</code></li> <li><code>post-release-dockerfile</code></li> <li><code>post-release-pack</code></li> </ul> </li> <li>The ability to call <code>logs:failed</code> without specifying an app or <code>--all</code> flag has been removed. This was deprecated in 0.22.0. Please see the logs:failed.</li> <li>The following app shell functions - deprecated since 0.20.0 - have been removed in favor of their plugin trigger equivalents. Sourcing the <code>app/functions</code> file will fail going forward.<ul> <li><code>apps#apps_create()</code> is removed in favor of <code>plugn trigger app-create</code>.</li> <li><code>apps#apps_destroy()</code> is removed in favor of <code>plugn trigger app-destroy</code>.</li> <li><code>apps#apps_exists()</code> is removed in favor of <code>plugn trigger app-exists</code>.</li> <li><code>apps#apps_maybe_create()</code> is removed in favor of <code>plugn trigger app-maybe-create</code>.</li> </ul> </li> <li>The following common shell functions have been removed:<ul> <li><code>common#is_container_running()</code> (deprecated since 0.12.6) is removed in favor of <code>common#is_container_status()</code>.</li> <li><code>common#is_app_running()</code> (deprecated since 0.22.0) is removed in favor of <code>ps#fn-ps-is-app-running()</code>.</li> </ul> </li> <li>The global <code>--rm-container</code> and <code>--rm</code> flags - deprecated since 0.25.0 - have been removed.</li> <li>The following git shell functions have been removed:<ul> <li><code>git#use_git_worktree()</code> (deprecated since 0.23.7) has been removed. There is no alternative as the function has been made internal.</li> <li><code>git#git_deploy_branch()</code>(deprecated since 0.21.0) has been removed in favor of <code>plugn trigger git-deploy-branch</code>.</li> </ul> </li> <li>The following nginx commands - deprecated since 0.20.0 - have been removed:<ul> <li><code>nginx:show-conf</code> has been removed in favor of <code>nginx:show-config</code>.</li> <li><code>nginx:validate</code> has been removed in favor of <code>nginx:validate-config</code>.</li> <li><code>nginx:build-config</code> - deprecated since 0.21.0 - has been removed in favor of <code>proxy:build-config</code>.</li> </ul> </li> <li>The following proxy functions - deprecated since 0.20.0 - have been removed in favor of their plugin trigger equivalents. Sourcing the <code>proxy/functions</code> file will fail going forward.<ul> <li><code>proxy#is_app_proxy_enabled()</code> is removed in favor of <code>plugn trigger proxy-is-enabled</code>.</li> <li><code>proxy#get_app_proxy_type()</code> is removed in favor of <code>plugn trigger proxy-type</code>.</li> </ul> </li> </ul>"},{"location":"appendices/0.31.0-migration-guide/","title":"0.31.0 Migration Guide","text":""},{"location":"appendices/0.31.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>Herokuish build cache is now mounted from a docker volume - eg. <code>cache-node-js-app</code> - instead of the local filesystem. All existing app cache will be cleared upon upgrading past 0.29.0.</li> <li>The <code>vector</code> container integration now mounts config to <code>/etc/vector</code> instead of the path <code>/etc/vector/vector.json</code>, allowing users the ability to provide extra configuration for Vector Sinks. To take advantage of the new functionality, the vector container should be stopped (via <code>dokku logs:vector-stop</code>) and then started (via <code>dokku logs:vector-start</code>).</li> <li>The <code>traefik</code> integration now mounts config to <code>/data</code> instead of the path <code>/acme.json</code>, fixing permissions issues under certain architectures. To take advantage of the new functionality, the traefik container should be stopped (via <code>dokku traefik:stop</code>) and then started (via <code>dokku traefik:start</code>).</li> <li>Users no longer need to clear the <code>source-image</code> git property when transitioning from image-based deploys (<code>git:from-image</code> and <code>git:load-image</code>) to other deployment methods (git push, <code>git:from-archive</code>, <code>git:sync</code>).</li> <li>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>CHECKS</code> file is now extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>CHECKS</code> extracted directly from the source code. The filename in both cases is <code>CHECKS</code> and cannot be modified.</li> <li>Port mappings are now auto-detected during the build process. Users may override detected port mappings via the <code>ports</code> plugin. A default port mapping of <code>http:80:5000</code> will be used if none is otherwise specified.</li> <li>Users building docker images that run Dokku will need to use a new sudoer wrapper for the <code>docker-container-healthchecker</code> binary to work correctly. A reference version has been placed in the <code>docker</code> skeleton directory. This should only impact platform developers, and users of our Docker image will already have the file available.</li> <li>The default image used for Herokuish Buildpack builds is now <code>gliderlabs/herokuish:latest-22</code>, and is based on both the <code>heroku-22</code> stack as well as Ubuntu 22.04. Users that wish to stick with the old, <code>heroku-20</code>/Ubuntu 20.04 builder may specify <code>gliderlabs/herokuish:latest-20</code> as their builder image. Please see the herokuish buildpack deployment documentation for more information on how to specify a custom buildpack stack builder.</li> <li>The default image used for Cloud Native Buildpack builds is now <code>heroku/builder:22</code>, and is based on both the <code>heroku-22</code> stack as well as Ubuntu 22.04. Users that wish to stick with the old, <code>heroku-20</code>/Ubuntu 20.04 builder may specify <code>heroku/buildpacks:20</code> as their builder image. Please see the herokuish buildpack deployment documentation for more information on how to specify a custom buildpack stack builder.</li> </ul>"},{"location":"appendices/0.31.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>The <code>proxy:ports*</code> commands have been replaced with the new <code>ports</code> plugin. Users will be able to use the old <code>proxy:ports*</code> commands for a single minor release, and they will be removed in the next minor release.</li> <li>The <code>common#get_available_port()</code> function has been deprecated and will be removed in the next release. Users should avoid interacting with this function and instead use the <code>ports-get-available</code> plugin trigger for fetching an available port.</li> <li>The <code>proxy-configure-ports</code> plugin trigger has been deprecated and will be removed in the next release. Users should instead trigger the <code>ports-configure</code> plugin trigger.</li> <li>The <code>common#get_dockerfile_exposed_ports()</code> function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was in the <code>builder-dockerfile</code> plugin.</li> <li>The <code>common#get_exposed_ports_from_image()</code> function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was during the build process.</li> <li>The environment variable <code>DOKKU_PROXY_PORT_MAP</code> has been migrated to the properties system. Direct changes to the value will be ignored, and users should interact with port maps via the <code>ports</code> plugin.</li> <li>The <code>CHECKS</code> file is deprecated in favor of defining healthchecks in the <code>app.json</code> file. The docker-container-healthchecker tool can be used to generate healthcheck entries in <code>app.json</code> format from existing <code>CHECKS</code> files. See the zero-downtime deploy documentation for more information on how the new zero downtime check format works.</li> <li>ARM support is now deprecated, and will be removed in the next minor release. ARM releases are not tested in CI and do not get testing locally. Users of ARM installations on platforms such as the Raspberry PI should consider migrating to ARM64. ARM64 will continue to be supported by Dokku, and there are no plans to remove support for ARM64.</li> </ul>"},{"location":"appendices/0.31.0-migration-guide/#un-deprecations","title":"Un-Deprecations","text":"<ul> <li>The bare <code>apps</code> and <code>config</code> cli aliases are no longer deprecated. This better follows Heroku's output and is more useful to users. The subcommands will be treated as the primary, documented versions, while the aliases are there for convenience.</li> </ul>"},{"location":"appendices/0.31.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>The variable <code>RAW_TCP_PORTS</code> is no longer exposed for <code>nginx.conf.sigil</code> templating.</li> <li>The environment variable <code>DOKKU_DOCKERFILE_PORTS</code> is no longer in use. Users wishing to change port mappings should instead use the <code>ports</code> plugin.</li> <li>The <code>common#get_app_raw_tcp_ports()</code> function has been removed in the next release. Users should instead use the <code>ports-get</code> plugin trigger for fetching ports for an app.</li> <li>The plugin trigger <code>network-compute-ports</code> has been removed. It's only use was in the <code>scheduler-docker-local</code> plugin, for exposing ports. It's functionality is now implemented via the <code>ports</code> plugin.</li> <li>The plugin trigger <code>network-get-port</code> has been removed. It's only use was in the <code>scheduler-docker-local</code> plugin, for recording ports. It's functionality is now implemented via the <code>ports</code> plugin.</li> </ul>"},{"location":"appendices/0.32.0-migration-guide/","title":"0.32.0 Migration Guide","text":""},{"location":"appendices/0.32.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>The following <code>pre-build-*</code> plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the <code>pre-build</code> plugin trigger.<ul> <li>pre-build-buildpack</li> <li>pre-build-dockerfile</li> <li>pre-build-lambda</li> <li>pre-build-pack</li> </ul> </li> <li>The following <code>pre-release-*</code> plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the <code>pre-release-builder</code> plugin trigger.<ul> <li>pre-release-buildpack</li> <li>pre-release-dockerfile</li> <li>pre-release-lambda</li> <li>pre-release-pack</li> </ul> </li> <li>The following <code>post-build-*</code> plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the <code>post-build</code> plugin trigger.<ul> <li>post-build-buildpack</li> <li>post-build-dockerfile</li> <li>post-build-lambda</li> <li>post-build-pack</li> </ul> </li> <li>The <code>CHECKS</code> file was deprecated in the previous release in favor of defining healthchecks in the <code>app.json</code> file. It's support and auto-migration to healthchecks in the <code>app.json</code> file will be removed in the next release. See the zero-downtime deploy documentation for more information on how the new zero downtime check format works.</li> </ul>"},{"location":"appendices/0.32.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>ARM support has been removed. Users of ARM installations on platforms such as the Raspberry PI should consider migrating to ARM64. ARM64 will continue to be supported by Dokku, and there are no plans to remove support for ARM64.</li> <li>The following proxy-port related code has been removed. It is replaced by the <code>ports</code> plugin and it's related plugin triggers.<ul> <li><code>proxy:ports-*</code> commands</li> <li><code>proxy-configure-ports</code> plugin trigger</li> <li><code>common#get_available_port()</code></li> <li><code>common#get_dockerfile_exposed_ports()</code></li> <li><code>common#get_exposed_ports_from_image()</code></li> </ul> </li> </ul>"},{"location":"appendices/0.5.0-migration-guide/","title":"0.5.0 Migration Guide","text":""},{"location":"appendices/0.5.0-migration-guide/#nginx-vhosts-plugin","title":"<code>nginx-vhosts</code> plugin","text":"<ul> <li>The nginx-vhosts template language is now sigil<ul> <li>No need to escape literal <code>$</code> characters (or other \"bash-isms\")</li> <li>Template variables are represented as {{ .VARIABLE_NAME }}</li> <li>A detailed list of template variables can be found here</li> </ul> </li> <li>A custom nginx-vhosts template must be named <code>nginx.conf.sigil</code><ul> <li>The default path for this custom template is the root of your repo (i.e. <code>/app</code> in the container or <code>WORKDIR</code> if defined in a dockerfile app)</li> <li>Dokku no longer looks for this file in <code>/home/dokku/node-js-app</code> on the Dokku server</li> <li>Check out an example template here</li> </ul> </li> <li>Support for server-wide SSL certs have been dropped in favor of using the <code>certs</code> plugin<ul> <li><code>dokku certs:add node-js-app &lt; certs.tar</code></li> </ul> </li> <li>All domains for an SSL-enabled app will be redirected to https by default<ul> <li>This can be overridden with a custom template</li> </ul> </li> <li>Replaced \"magic\" <code>NO_VHOST</code> variable with <code>domains:enable/disable</code></li> <li>Simplified zero downtime control<ul> <li><code>checks:enable/disable</code></li> </ul> </li> </ul>"},{"location":"appendices/0.5.0-migration-guide/#dockerfile-apps-with-exposed-ports","title":"Dockerfile apps with exposed ports","text":"<ul> <li>Dockerfiles with <code>EXPOSE</code> clauses will get all tcp ports proxied by default<ul> <li>Note that nginx will proxy the same port numbers to listen publicly</li> <li>UDP ports can be exposed by disabling the nginx proxy with <code>dokku proxy:disable node-js-app</code></li> </ul> </li> </ul>"},{"location":"appendices/0.6.0-migration-guide/","title":"0.6.0 Migration Guide","text":""},{"location":"appendices/0.6.0-migration-guide/#zero-downtime-deployment","title":"Zero-downtime deployment","text":"<ul> <li>You can now actually disable zero-downtime deployments per-app and per-process-type<ul> <li>Some config variables have been moved around<ul> <li><code>DOKKU_CHECKS_ENABLED</code> has been migrated to <code>DOKKU_CHECKS_SKIPPED</code></li> <li><code>DOKKU_CHECKS_DISABLED</code> is now a thing</li> <li>The values for the above can be a comma-separated list of process-types or the literal string <code>_all_</code></li> </ul> </li> <li>See the updated <code>checks</code> docs for more info</li> </ul> </li> </ul>"},{"location":"appendices/0.6.0-migration-guide/#proxy-port-mapping","title":"Proxy port mapping","text":"<ul> <li>You can now configure host -&gt; container proxy port mappings<ul> <li>The UI is handled by the proxy interface plugin by setting the <code>DOKKU_PROXY_PORT_MAP</code> config variable in the format of <code>scheme:host-port:container-port</code>. The default <code>nginx-vhosts</code> proxy plugin supports both the <code>http</code> and <code>https</code> schemes.</li> </ul> </li> <li>Default port mappings<ul> <li>buildpack apps will be set to <code>http:80:5000</code> and will also include <code>https:443:5000</code> if SSL is enabled.</li> <li>dockerfile apps with explicitly exposed ports (i.e. using the <code>EXPOSE</code> directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container.<ul> <li>You may override this behavior with the <code>proxy:ports-*</code> commands or by directly setting <code>DOKKU_PROXY_PORT_MAP</code> with the <code>config:set</code> command</li> <li>dockerfile apps without explicitly exposed ports will behave the same as a buildpack app</li> </ul> </li> <li>NOTE: These defaults are not automatically changed on subsequent pushes and must be manipulated with the aforementioned commands</li> </ul> </li> </ul>"},{"location":"appendices/0.6.0-migration-guide/#calling-the-dokku-binary","title":"Calling the <code>dokku</code> binary","text":"<ul> <li>Plugins should not call the <code>dokku</code> binary directly. Clients using the <code>--app</code> argument are potentially broken, amongst others, when doing so. Instead, please source the <code>functions</code> file for a given plugin when attempting to call Dokku internal functions. As a result, the following Dokku commands are no longer publicly exposed:<ul> <li><code>dokku build</code></li> <li><code>dokku receive</code></li> <li><code>dokku release</code></li> <li><code>dokku tar:build</code></li> <li><code>dokku tar:build-locked</code></li> <li><code>dokku git:build</code></li> <li><code>dokku git:build-locked</code></li> </ul> </li> </ul>"},{"location":"appendices/0.7.0-migration-guide/","title":"0.7.0 Migration Guide","text":""},{"location":"appendices/0.7.0-migration-guide/#persistent-storage","title":"Persistent Storage","text":"<p>We should now properly handle file ownership for mounted directories. This was enhanced in 0.7.1. See the persistent storage documentation for more details.</p>"},{"location":"appendices/0.7.0-migration-guide/#restart-policies","title":"Restart Policies","text":"<p>If you previously managed container restart policies via docker-options, these can now be managed natively via the built-in <code>ps</code> plugin. There is no migration necessary. See the restart policy documentation for more details.</p>"},{"location":"appendices/0.7.0-migration-guide/#ssh-keys","title":"SSH Keys","text":"<p>Dokku now has an <code>ssh-keys</code> plugin that can be used to manage ssh keys for the <code>dokku</code> user on the host operating system. See the user management documentation for more details.</p>"},{"location":"appendices/0.8.0-migration-guide/","title":"0.8.0 Migration Guide","text":""},{"location":"appendices/0.8.0-migration-guide/#domain-management","title":"Domain Management","text":"<p>You can now set global and app domains via <code>domains:set</code> and <code>domains:set-global</code>. See the domains documentation for more details.</p>"},{"location":"appendices/0.8.0-migration-guide/#plugin-uninstallation","title":"Plugin Uninstallation","text":"<p>A new <code>uninstall</code> plugin trigger was introduced. This functionality may be in use for newer plugins, so be aware that older Dokku versions may require manual cleanup.</p> <p>See the uninstall trigger documentation for implementation instructions.</p>"},{"location":"appendices/0.8.0-migration-guide/#deployment-tasks","title":"Deployment Tasks","text":"<p>Should a pre or post deployment task fail, we now fail the entire deploy.</p>"},{"location":"appendices/0.8.0-migration-guide/#nginx-http2-support","title":"Nginx HTTP2 Support","text":"<p>Due to bugs in Nginx, the minimum version for HTTP2 is now 1.11.5.</p>"},{"location":"appendices/0.9.0-migration-guide/","title":"0.9.0 Migration Guide","text":""},{"location":"appendices/0.9.0-migration-guide/#golang-migration","title":"Golang Migration","text":"<p>There is an ongoing migration to rewrite Dokku in Golang. The reasons are beyond the scope of this document, but this may impact any patches you have for Dokku. As of 0.9.0, only the <code>repo</code> plugin is in Golang.</p> <p>The following shall remain true, regardless of the state of our rewrite:</p> <ul> <li>You will be able to write custom plugins in any language.</li> <li>You will be able to enable or disable core plugins.</li> <li><code>plugn</code> will continue to be used for executing plugin triggers.</li> <li>We will provide bash wrappers that can be sourced to execute core functionality that is implemented in golang.</li> </ul>"},{"location":"community/clients/","title":"Clients","text":"<p>Given the constraints, running Dokku commands remotely via SSH is fine. For certain configurations, the extra complication of manually invoking ssh can be a burden.</p> <p>The easiest way to interact with Dokku remotely is by using the official client. Documented below are the various clients that you may wish to use.</p>"},{"location":"community/clients/#official-client","title":"Official Client","text":"<p>See the remote commands documentation for more information on how to install and use the official client.</p>"},{"location":"community/clients/#nodejs-dokku-toolbelt","title":"(nodejs) dokku-toolbelt","text":"<p>Dokku-toolbelt is a node-based cli wrapper that proxies requests to the Dokku command running on remote hosts. You can install it via the following shell command (assuming you have nodejs and npm installed):</p> <pre><code>npm install -g dokku-toolbelt\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dokku-cli","title":"(ruby) Dokku CLI","text":"<p>Dokku CLI is a rubygem that acts as a client for your Dokku installation. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dokku-cli\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dokkuclient","title":"(ruby) DokkuClient","text":"<p>DokkuClient is another rubygem that acts as a client for your Dokku installation with built-in support for certain external plugins. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dokku_client\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dokkufy","title":"(ruby) Dokkufy","text":"<p>Dokkufy is a rubygem that handles automation of certain tasks, such as Dokku setup, plugin installation, etc. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dokkufy\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dockland","title":"(ruby) Dockland","text":"<p>Dockland is a rubygem that acts as a client for your Dokku installation. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dockland\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/plugins/","title":"Plugins","text":"<p>Dokku itself is built out of plugins and uses plugn for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.</p> <p>Let's take a quick look at the current Dokku nginx plugin that's shipped with Dokku by default.</p> <pre><code>nginx-vhosts/\n\u251c\u2500\u2500 plugin.toml  # plugin metadata\n\u251c\u2500\u2500 commands     # contains additional commands\n\u251c\u2500\u2500 install      # runs on Dokku installation\n\u2514\u2500\u2500 post-deploy  # runs after an app is deployed\n</code></pre>"},{"location":"community/plugins/#installing-a-plugin","title":"Installing a plugin","text":"<p>See the plugin management documentation.</p>"},{"location":"community/plugins/#creating-your-own-plugin","title":"Creating your own plugin","text":"<p>See the full documentation.</p>"},{"location":"community/plugins/#official-plugins","title":"Official Plugins","text":"<p>The following plugins are available and provided by Dokku maintainers.  Please file issues against their respective issue trackers.</p> Plugin Author Compatibility Clickhouse dokku 0.4.0+ Copy Files to Image dokku 0.4.0+ CouchDB dokku 0.4.0+ Cron Restart dokku 0.30.0+ Elasticsearch dokku 0.4.0+ Grafana/Graphite/Statsd dokku 0.4.0+ HTTP Auth dokku 0.4.0+ Let's Encrypt dokku 0.4.0+ Maintenance mode dokku 0.4.0+ MariaDB dokku 0.4.0+ Meilisearch dokku 0.4.0+ Memcached dokku 0.4.0+ Mongo dokku 0.4.0+ MySQL dokku 0.4.0+ Nats dokku 0.4.0+ Omnisci dokku 0.4.0+ Postgres dokku 0.4.0+ Pushpin dokku 0.4.0+ RabbitMQ dokku 0.4.0+ Redirect dokku 0.4.0+ Redis dokku 0.4.0+ Registry dokku 0.12.0+ RethinkDB dokku 0.4.0+ Scheduler Kubernetes dokku 0.4.0+ Scheduler Nomad dokku 0.4.0+ Solr dokku 0.4.0+ SSH Hostkeys dokku 0.4.0+ Typesense dokku 0.4.0+"},{"location":"community/plugins/#community-plugins","title":"Community plugins","text":"<p>Warning</p> <p>The following plugins have been supplied by our community and may not have been tested by Dokku maintainers.</p>"},{"location":"community/plugins/#datastores","title":"Datastores","text":""},{"location":"community/plugins/#relational","title":"Relational","text":"Plugin Author Compatibility MariaDB kloadut 0.3.x MariaDB (single container) ohardy 0.3.x MariaDB (single container) krisrang 0.3.26+ PostgreSQL jlachowski 0.3.x PostgreSQL (single container) ohardy 0.3.x PostgreSQL (single container) flink 0.3.26+ Edgedb ignisda 0.27.0+"},{"location":"community/plugins/#newsql","title":"NewSQL","text":"Plugin Author Compatibility Surrealdb ignisda 0.27.0+"},{"location":"community/plugins/#caching","title":"Caching","text":"Plugin Author Compatibility Nginx Cache aluxian 0.5.0+ Redis (single container) ohardy 0.3.x Varnish zenedith Varnish cache between nginx and application with base configuration"},{"location":"community/plugins/#queuing","title":"Queuing","text":"Plugin Author Compatibility RabbitMQ jlachowski 0.3.x RabbitMQ (single container) jlachowski 0.3.x ElasticMQ (SQS compatible) cu12 0.5.0+ VerneMQ (MQTT Broker) mrname 0.4.0+"},{"location":"community/plugins/#other","title":"Other","text":"Plugin Author Compatibility etcd basgys 0.4.x FakeSNS cu12 0.5.0+ InfluxDB basgys 0.4.x RethinkDB stuartpb 0.3.x Headless Chrome lazyatom 0.8.1+"},{"location":"community/plugins/#plugins-implementing-new-dokku-functionality","title":"Plugins Implementing New Dokku Functionality","text":"Plugin Author Compatibility App name as env cjblomqvist 0.3.x APT dokku-community 0.18.x+ Auto Sync<sup>1</sup> fomojola 0.8.1+ Deploy Webhook<sup>2</sup> fomojola 0.8.1+ Docker auto persist volumes flink 0.4.0+ Docker Direct josegonzalez 0.4.0+ Dokku Clone crisward 0.4.0+ Dokku Copy App Config Files josegonzalez 0.4.0+ Dokku Require<sup>3</sup> crisward 0.4.0+ Global Certificates josegonzalez 0.5.0+ Graduate (Environment Management) benjamin-dobell 0.4.0+ Host post-build command hook baikunz 0.4.0+ Host pre-build command hook fteychene 0.4.0+ Hostname michaelshobbs 0.4.0+ Hostname michaelshobbs 0.4.0+ HTTP Auth Secure Apps matto1990 0.4.0+ Litestream<sup>4</sup> AxelTheGerman 0.27.0+ Monit (Health Checks) mbreit 0.8.0+ Monit cjblomqvist 0.3.x Nuke Containers josegonzalez 0.4.0+ Proctype Filter michaelshobbs 0.4.0+ robots.txt candlewaster 0.4.x Tor michaelshobbs 0.4.0+ UFW josegonzalez 0.3.x User Access mainto 0.4.0+ User ACL maciej \u0142ebkowski 0.4.0+ <p><sup>1</sup> Adds the ability to sync an application repo with a remote GitHub repo (useful for automated rebuilds without needing a git push from an external system</p> <p><sup>2</sup> Adds the ability to invoke a post-deploy webhook with the IP, port and app name, all with a single config:set).</p> <p><sup>3</sup> Extends app.json support to include creating volumes and creating / linking databases on push</p> <p><sup>4</sup> Adds SQLite replication to external object storage via Litestream</p>"},{"location":"community/plugins/#other-plugins","title":"Other Plugins","text":"Plugin Author Compatibility Chef cookbook nickcharlton Discourse badsyntax 0.21.4+ Wordpress dokku-community 0.4.0+"},{"location":"community/plugins/#deprecated-plugins","title":"Deprecated Plugins","text":"<p>The following plugins have been removed as their functionality is now in Dokku Core.</p> Plugin Author In Dokku Since Airbrake deploy flink v0.5.0 (deployment tasks) App User michaelshobbs v0.7.1 (herokuish 0.3.18) Bower/Grunt thrashr888 v0.5.0 (deployment tasks and .buildpacks) Bower/Gulp gdi2290 v0.5.0 (deployment tasks and .buildpacks) Bower install alexanderbeletsky v0.5.0 (deployment tasks and .buildpacks) Bower/Gulp jagandecapri v0.5.0 (deployment tasks and .buildpacks) Builders: bower, compass, gulp, grunt ignlg v0.5.0 (deployment tasks and .buildpacks) Custom Domains neam v0.3.10 (domains plugin) Debug josegonzalez v0.3.9 (trace command) Dockerfile custom path mimischi v0.25.0 (monorepo support) Docker Options dyson v0.3.17 (docker-options plugin) Dokku Name alex-sherwin v0.4.2 (named containers plugin) Events Logger alessio v0.3.21 (events plugin) Fonts ollej v0.5.0 (deployment tasks) git rev-parse HEAD in env cjblomqvist v0.12.0 (enhanced core git plugin) Host Port binding stuartpb v0.3.17 (docker-options plugin) Link Containers rlaneve v0.3.17 (docker-options plugin) List Containers josegonzalez v0.3.14 (ps plugin) Logspout michaelshobbs v0.22.6 (vector log shipping) Long Timeout investtools v0.21.0 (proxy-read-timeout nginx setting) Monorepo iamale v0.25.0 (monorepo builder support) Multi-Buildpack pauldub v0.4.0 (herokuish) Multiple Domains<sup>1</sup> wmluke v0.3.10 (domains plugin) Multi Dockerfile artofrawr v0.25.0 (monorepo support) Named-containers flink v0.4.2 (named-containers plugin) Nginx Trust Proxy kingsquare v0.23.0 (nginx x-forwarded-* properties) Node ademuk v0.5.0 (deployment tasks and .buildpacks) Node pnegahdar v0.5.0 (deployment tasks and .buildpacks) Nginx-Alt mikexstudios v0.3.10 (domains plugin) Persistent Storage dyson v0.3.17 (docker-options plugin) Pre-Deploy Tasks michaelshobbs v0.5.0 (deployment tasks) PrimeCache darkpixel v0.3.0 (zero downtime deploys) Rollbar iloveitaly v0.5.0 (deployment tasks) Syslog michaelshobbs v0.22.6 (vector log shipping) Haproxy tcp load balancer 256dpi v0.28.0 (haproxt plugin) Process Manager: Circus apmorton v0.3.14/0.7.0 (ps/restart policy plugin) Process Manager: Forego flink v0.3.14/0.7.0 (ps plugin) Process Manager: Forego iskandar v0.3.14/0.7.0 (ps plugin) Process Manager: Logging Supervisord sehrope v0.3.14/0.7.0 (ps plugin) Process Manager: Shoreman statianzo v0.3.14/0.7.0 (ps plugin) Process Manager: Supervisord statianzo v0.3.14/0.7.0 (ps plugin) Rebuild application scottatron v0.3.14 (ps plugin) Reset mtime mixxorz Docker 1.8+ SSH Deployment Keys dokku v0.33.0 (git plugin) Supply env vars to buildpacks<sup>2</sup> cameron-martin v0.3.9 (build-env plugin) Slack Notifications ribot v0.5.0 (deployment tasks) Telegram Notifications m0rth1um v0.5.0 (deployment tasks) user-env-compile<sup>2</sup> motin v0.3.9 (build-env plugin) user-env-compile<sup>2</sup> musicglue v0.3.9 (build-env plugin) Volume (persistent storage) ohardy v0.5.0 (storage plugin) Webhooks nickstenning v0.5.0 (deployment tasks) Wkhtmltopdf mbriskar v0.5.0 (deployment tasks) <p><sup>1</sup> Conflicts with VHOSTS Custom Configuration <sup>2</sup> Similar to the heroku-labs feature</p>"},{"location":"community/plugins/#unmaintained-plugins","title":"Unmaintained Plugins","text":"<p>The following plugins are no longer maintained by their developers.</p> Plugin Author Compatibility app-url mikecsh Works with 0.2.0 Chef cookbooks fgrehm CouchDB (multi containers) flink 0.4.0+ CouchDB raceHub Compatible with 0.2.0 Dokku Copy App Config Files alexkruegger Compatible with 0.3.17+ Dokku Registry agco-adm 0.4.0+ Elasticsearch robv Not compatible with &gt;= 0.3.0 (still uses /home/git) Elasticsearch<sup>1</sup> blag Compatible with 0.2.0 Graphite/statsd jlachowski &lt; 0.4.0 HipChat Notifications cef Memcached flink 0.4.0+ MongoDB (single container) jeffutter MySQL hughfletcher Neo4j aomitayo PostGIS fermuch PostgreSQL (single container) jeffutter This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory). Redis luxifer Redis sekjun9878 0.3.26+ RiakCS (single container) jeffutter Incompatible with 0.2.0 <p><sup>1</sup> Forked from jezdez/dokku-elasticsearch-plugin: uses Elasticsearch 1.2 (instead of 0.90), doesn't depend on dokku-link, runs as elasticsearch user instead of root, and turns off multicast autodiscovery for use in a VPS environment.</p>"},{"location":"configuration/domains/","title":"Domain Configuration","text":"<p>New</p> <p>Introduced in 0.3.10</p> <pre><code>domains:add &lt;app&gt; &lt;domain&gt; [&lt;domain&gt; ...]      # Add domains to app\ndomains:add-global &lt;domain&gt; [&lt;domain&gt; ...]     # Add global domain names\ndomains:clear &lt;app&gt;                            # Clear all domains for app\ndomains:clear-global                           # Clear global domain names\ndomains:disable &lt;app&gt;                          # Disable VHOST support\ndomains:enable &lt;app&gt;                           # Enable VHOST support\ndomains:remove &lt;app&gt; &lt;domain&gt; [&lt;domain&gt; ...]   # Remove domains from app\ndomains:remove-global &lt;domain&gt; [&lt;domain&gt; ...]  # Remove global domain names\ndomains:report [&lt;app&gt;|--global] [&lt;flag&gt;]       # Displays a domains report for one or more apps\ndomains:set &lt;app&gt; &lt;domain&gt; [&lt;domain&gt; ...]      # Set domains for app\ndomains:set-global &lt;domain&gt; [&lt;domain&gt; ...]     # Set global domain names\n</code></pre> <p>Info</p> <p>Adding a domain before deploying an application will result in port mappings being set. This may cause issues for applications that use non-standard ports, as those will not be automatically detected. Please refer to the proxy documentation for information as to how to reconfigure the mappings.</p>"},{"location":"configuration/domains/#customizing-hostnames","title":"Customizing hostnames","text":"<p>Applications typically have the following structure for their hostname:</p> <pre><code>scheme://subdomain.domain.tld\n</code></pre> <p>The <code>subdomain</code> is inferred from the pushed application name, while the <code>domain.tld</code> is set during initial dokku configuration. It can then be modified with <code>dokku domains:add-global</code> and <code>dokku domains:remove-global</code>. This value is used as a default TLD for all applications on a host.</p> <p>If an FQDN such as <code>dokku.org</code> is used as the application name, the global virtualhost will be ignored and the resulting vhost URL for that application will be <code>dokku.org</code>.</p> <p>You can optionally override this in a plugin by implementing the <code>nginx-hostname</code> plugin trigger. If the <code>nginx-hostname</code> plugin has no output, the normal hostname algorithm will be executed. See the plugin trigger documentation for more information.</p>"},{"location":"configuration/domains/#disabling-vhosts","title":"Disabling VHOSTS","text":"<p>If desired, it is possible to disable vhosts with the domains plugin.</p> <pre><code>dokku domains:disable node-js-app\n</code></pre> <p>On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting <code>DOKKU_PROXY_PORT</code> and/or <code>DOKKU_PROXY_SSL_PORT</code> (for services configured to use SSL.)</p> <p>The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via <code>certs:add</code>. Be aware that disabling domains (with <code>domains:disable</code>) will override any custom domains.</p> <pre><code># where `node-js-app` is the name of your app\n\n# add a domain to an app\ndokku domains:add node-js-app dokku.me\n\n# list custom domains for app\ndokku domains:report node-js-app\n\n# clear all custom domains for app\ndokku domains:clear node-js-app\n\n# remove a custom domain from app\ndokku domains:remove node-js-app dokku.me\n\n# set all custom domains for app\ndokku domains:set node-js-app dokku.me dokku.org\n</code></pre>"},{"location":"configuration/domains/#displaying-domains-reports-for-an-app","title":"Displaying domains reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's domains status using the <code>domains:report</code> command:</p> ShellOutput <pre><code>dokku domains:report\n</code></pre> <pre><code>=====&gt; node-js-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  node-js-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n=====&gt; python-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  python-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n=====&gt; ruby-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  ruby-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku domains:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  node-js-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku domains:report node-js-app --domains-app-enabled\n</code></pre>"},{"location":"configuration/domains/#default-site","title":"Default site","text":"<p>This is specific to your proxy plugin of choice. See the nginx documentation for more information on how to configure this for the default nginx proxy implementation.</p>"},{"location":"configuration/environment-variables/","title":"Environment Variables","text":"<p>Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommended to store them in your application's repository.</p> <p>The <code>config</code> plugin provides the following commands to manage your variables:</p> <pre><code>config:show (&lt;app&gt;|--global)                                                          Pretty-print an app or global environment\nconfig:bundle (&lt;app&gt;|--global) [--merged]                                             Bundle environment into tarfile\nconfig:clear (&lt;app&gt;|--global)                                                         Clears environment variables\nconfig:export (&lt;app&gt;|--global) [--envfile]                                            Export a global or app environment\nconfig:get (&lt;app&gt;|--global) KEY                                                       Display a global or app-specific config value\nconfig:keys (&lt;app&gt;|--global) [--merged]                                               Show keys set in environment\nconfig:set [--encoded] [--no-restart] (&lt;app&gt;|--global) KEY1=VALUE1 [KEY2=VALUE2 ...]  Set one or more config vars\nconfig:unset [--no-restart] (&lt;app&gt;|--global) KEY1 [KEY2 ...]                          Unset one or more config vars\n</code></pre> <p>Info</p> <p>For security reasons - and as per docker recommendations - Dockerfile-based deploys have variables available only during runtime, as noted in this issue. Consider using build arguments to expose variables during build-time for Dockerfile apps.</p> <p>Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys.</p> <p>For buildpack deploys, Dokku will create a  <code>/app/.env</code> file that can be used for legacy buildpacks. Note that this is not updated when <code>config:set</code> or <code>config:unset</code> is called, and is only written during a <code>deploy</code> or <code>ps:rebuild</code>. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.</p> <p>Note</p> <p>Global <code>ENV</code> files are sourced before app-specific <code>ENV</code> files. This means that app-specific variables will take precedence over global variables. Configuring your global <code>ENV</code> file is manual, and should be considered potentially dangerous as configuration applies to all applications.</p> <p>You can set multiple environment variables at once:</p> <pre><code>dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1\n</code></pre> <p>Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:</p> <pre><code>dokku config:set node-js-app KEY=\"VAL\\ WITH\\ SPACES\"\n</code></pre> <p>Dokku can also read base64 encoded values. That's the easiest way to set a value with newlines or spaces. To set a value with newlines you need to base64 encode it first and pass the <code>--encoded</code> flag:</p> <pre><code>dokku config:set --encoded node-js-app KEY=\"$(base64 ~/.ssh/id_rsa)\"\n</code></pre> <p>When setting or unsetting environment variables, you may wish to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the <code>--no-restart</code> flag:</p> <pre><code>dokku config:set --no-restart node-js-app ENV=prod\n</code></pre> <p>If you wish to have the variables output in an <code>eval</code>-compatible form, you can use the <code>config:export</code> command</p> <pre><code>dokku config:export node-js-app\n# outputs variables in the form:\n#\n#   export ENV='prod'\n#   export COMPILE_ASSETS='1'\n\n# source in all the node-js-app app environment variables\neval $(dokku config:export node-js-app)\n</code></pre> <p>You can control the format of the exported variables with the <code>--format</code> flag. <code>--format=shell</code> will output the variables in a single-line for usage in command-line utilities:</p> <pre><code>dokku config:export --format shell node-js-app\n\n# outputs variables in the form:\n#\n#   ENV='prod' COMPILE_ASSETS='1'\n</code></pre>"},{"location":"configuration/environment-variables/#special-config-variables","title":"Special Config Variables","text":"<p>The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future.</p> <p>Warning</p> <p>This list is not exhaustive, and may vary from version to version.</p> Name Default How to modify Description <code>DOKKU_ROOT</code> <code>~dokku</code> <code>/etc/environment</code> The root directory where dokku will store application repositories, as well as certain configuration files. <code>DOKKU_IMAGE</code> <code>gliderlabs/herokuish</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The default image to use when building herokuish containers. Deprecated in favor of using <code>buildpacks:set-property</code> <code>DOKKU_LIB_ROOT</code> <code>/var/lib/dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory where plugins, certain data, and general configuration is stored. <code>PLUGIN_PATH</code> <code>$DOKKU_LIB_ROOT/plugins\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The top-level directory where plugins are stored. <code>PLUGIN_AVAILABLE_PATH</code> <code>$PLUGIN_PATH/available\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that holds all available plugins, including core. <code>PLUGIN_ENABLED_PATH</code> <code>$PLUGIN_PATH/enabled\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that holds all enabled plugins, including core. <code>PLUGIN_CORE_PATH</code> <code>$DOKKU_LIB_ROOT/core-plugins\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that stores all core plugins. <code>PLUGIN_CORE_AVAILABLE_PATH</code> <code>$PLUGIN_CORE_PATH/available\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that stores all available core plugins. <code>PLUGIN_CORE_ENABLED_PATH</code> <code>$PLUGIN_CORE_PATH/enabled\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that stores all enabled core plugins. <code>DOKKU_LOGS_DIR</code> <code>/var/log/dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Where dokku logs should be written to. <code>DOKKU_LOGS_HOST_DIR</code> <code>$DOKKU_LOGS_DIR</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> A path on the host that will be mounted into the vector logging container. <code>DOKKU_EVENTS_LOGFILE</code> <code>$DOKKU_LOGS_DIR/events.log</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Where the events log file is written to. <code>DOKKU_APP_NAME</code> none <code>--app APP</code> flag Name of application to work on. Respected by core plugins. <code>DOKKU_APPS_FORCE_DELETE</code> none <code>--force</code> flag Whether to force delete an application. Also used by other plugins for destructive actions. <code>DOKKU_CHECKS_URL</code> <code>https://dokku.com/docs/deployment/zero-downtime-deploys/</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Url displayed during deployment when no CHECKS file exists. <code>DOKKU_QUIET_OUTPUT</code> none <code>--quiet</code> flag Silences certain header output for <code>dokku</code> commands. <code>DOKKU_RM_CONTAINER</code> none <code>dokku config:set</code> Deprecated: Whether to keep <code>dokku run</code> containers around or not. <code>DOKKU_TRACE</code> none <code>dokku trace:on</code> <code>dokku trace:off</code> <code>--trace</code> flag Turn on very verbose debugging. <code>DOKKU_APP_PROXY_TYPE</code> <code>nginx</code> <code>dokku proxy:set</code> <code>DOKKU_APP_RESTORE</code> <code>1</code> <code>dokku config:set</code> <code>dokku ps:stop</code> <code>DOKKU_APP_SHELL</code> <code>/bin/bash</code> <code>dokku config:set</code> Allows users to change the default shell used by Dokku for <code>dokku enter</code> and execution of deployment tasks. <code>DOKKU_APP_TYPE</code> <code>herokuish</code> Auto-detected by using buildpacks or dockerfile <code>DOKKU_CHECKS_DISABLED</code> none <code>dokku checks:disable</code> <code>DOKKU_CHECKS_ENABLED</code> none <code>dokku checks:enable</code> <code>DOKKU_CHECKS_SKIPPED</code> none <code>dokku checks:skip</code> <code>DOKKU_CHECKS_WAIT</code> <code>5</code> <code>dokku config:set</code> Wait this many seconds for the container to start before running checks. <code>DOKKU_CHECKS_TIMEOUT</code> <code>30</code> <code>dokku config:set</code> Wait this many seconds for each response before marking it as a failure. <code>DOKKU_CHECKS_ATTEMPTS</code> <code>5</code> <code>dokku config:set</code> Number of retries for to run for a specific check before marking it as a failure <code>DOKKU_DEFAULT_CHECKS_WAIT</code> <code>10</code> <code>dokku config:set</code> If no user-defined checks are specified - or if the process being checked is not a <code>web</code> process - this is the period of time Dokku will wait before checking that a container is still running. <code>DOKKU_DISABLE_PROXY</code> none <code>dokku proxy:disable</code> <code>dokku proxy:enable</code> Disables the proxy in front of your application, resulting in publicly routing the docker container. <code>DOKKU_DISABLE_ANSI_PREFIX_REMOVAL</code> none <code>dokku config:set</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Disables removal of the ANSI prefix during deploys. Can be used in cases where the client deployer does not understand ansi escape  codes. <code>DOKKU_DISABLE_APP_AUTOCREATION</code> none <code>dokku config:set</code> Disables automatic creation of a non-existent app on deploy. <code>DOKKU_DOCKER_STOP_TIMEOUT</code> <code>10</code> <code>dokku config:set</code> Configurable grace period given to the <code>docker stop</code> command. If a container has not stopped by this time, a <code>kill -9</code> signal or equivalent is sent in order to force-terminate the container. Both the <code>ps:stop</code> and <code>apps:destroy</code> commands also respect this value. If not specified, the docker defaults for the docker stop command will be used. <code>DOKKU_DOCKERFILE_CACHE_BUILD</code> none <code>dokku config:set</code> <code>DOKKU_DOCKERFILE_START_CMD</code> none <code>dokku config:set</code> <code>DOKKU_PARALLEL_ARGUMENTS</code>. none <code>dokku config:set</code> Allows passing custom arguments to parallel for <code>ps:*all</code> commands <code>DOKKU_PROXY_PORT</code> automatically assigned <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> <code>dokku config:set</code> <code>DOKKU_PROXY_SSL_PORT</code> automatically assigned <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> <code>dokku config:set</code> <code>DOKKU_SKIP_ALL_CHECKS</code> none <code>dokku config:set</code> <code>DOKKU_SKIP_CLEANUP</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. <code>DOKKU_SKIP_DEFAULT_CHECKS</code> <code>dokku config:set</code> <code>DOKKU_SKIP_DEPLOY</code> <code>dokku config:set</code> <code>DOKKU_START_CMD</code> none <code>dokku config:set</code> Command to run instead of <code>/start $PROC_TYPE</code> <code>DOKKU_SYSTEM_GROUP</code> <code>dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> System group to chown files as. <code>DOKKU_SYSTEM_USER</code> <code>dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> System user to chown files as."},{"location":"configuration/ssl/","title":"SSL Configuration","text":"<p>New</p> <p>Introduced in 0.4.0</p> <p>Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the <code>certs</code> plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled.</p> <pre><code>certs:add &lt;app&gt; CRT KEY                  # Add an ssl endpoint to an app. Can also import from a tarball on stdin.\ncerts:generate &lt;app&gt; DOMAIN              # Generate a key and certificate signing request (and self-signed certificate)\ncerts:remove &lt;app&gt;                       # Remove an SSL Endpoint from an app.\ncerts:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays an ssl report for one or more apps\ncerts:show &lt;app&gt; &lt;crt|key&gt;               # Show the server.crt or server.key on stdout\ncerts:update &lt;app&gt; CRT KEY               # Update an SSL Endpoint on an app. Can also import from a tarball on stdin\n</code></pre> <pre><code># for 0.3.x\ndokku nginx:import-ssl &lt;app&gt; &lt; certs.tar\n</code></pre> <p>Info</p> <p>Adding an ssl certificate before deploying an application will result in port mappings being updated. This may cause issues for applications that use non-standard ports, as those may not be automatically detected. Please refer to the proxy documentation for information as to how to reconfigure the mappings.</p>"},{"location":"configuration/ssl/#per-application-certificate-management","title":"Per-application certificate management","text":"<p>Dokku provides built-in support for managing SSL certificates on a per-application basis. SSL is managed via nginx outside of application containers, and as such can be updated on-the-fly without rebuilding containers. At this time, applications only support a single SSL certificate at a time. To support multiple domains for a single application, wildcard certificate usage is encouraged.</p>"},{"location":"configuration/ssl/#certificate-setting","title":"Certificate setting","text":"<p>The <code>certs:add</code> command can be used to push a <code>tar</code> containing a certificate <code>.crt</code> and <code>.key</code> file to a single application. The command should correctly handle cases where the <code>.crt</code> and <code>.key</code> are not named properly or are nested in a subdirectory of said <code>tar</code> file. You can import it as follows:</p> <pre><code>tar cvf cert-key.tar server.crt server.key\ndokku certs:add node-js-app &lt; cert-key.tar\n</code></pre> <p>Note</p> <p>If your <code>.crt</code> file came alongside a <code>.ca-bundle</code>, you'll want to concatenate those into a single <code>.crt</code> file before adding it to the <code>.tar</code>.</p> <pre><code>cat yourdomain_com.crt yourdomain_com.ca-bundle &gt; server.crt\n</code></pre>"},{"location":"configuration/ssl/#ssl-and-multiple-domains","title":"SSL and Multiple Domains","text":"<p>When an SSL certificate is associated to an application, the certificate will be associated with all domains currently associated with said application. Your certificate should be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the domain configuration documentation.</p> <p>Note that with the default nginx template, requests will be redirected to the <code>https</code> version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the nginx documentation.</p>"},{"location":"configuration/ssl/#certificate-generation","title":"Certificate generation","text":"<p>Note</p> <p>Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.</p> <p>The <code>certs:generate</code> command will walk you through the correct <code>openssl</code> commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration.</p> <p>If you decide to obtain a CA signed certificate, you can import that certificate using the aforementioned <code>dokku certs:add</code> command.</p>"},{"location":"configuration/ssl/#certificate-removal","title":"Certificate removal","text":"<p>The <code>certs:remove</code> command only works on app-specific certificates. It will <code>rm</code> the app-specific tls directory, rebuild the nginx configuration, and reload nginx.</p>"},{"location":"configuration/ssl/#showing-the-certificate","title":"Showing the certificate","text":"<p>The <code>certs:show</code> command can be used to show your configured certs for an app. The show command can be used for example to export Let's Encrypt certificates after they've been generated. You can export it as follows:</p> <pre><code>dokku certs:show node-js-app crt &gt; server.crt\ndokku certs:show node-js-app key &gt; server.key\n</code></pre>"},{"location":"configuration/ssl/#displaying-certificate-reports-for-an-app","title":"Displaying certificate reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the apps ssl status using the <code>certs:report</code> command:</p> ShellOutput <pre><code>dokku certs:report\n</code></pre> <pre><code>=====&gt; node-js-app\n       Ssl dir:             /home/dokku/node-js-app/tls\n       Ssl enabled:         true\n       Ssl hostnames:       *.node-js-app.org node-js-app.org\n       Ssl expires at:      Oct  5 23:59:59 2019 GMT\n       Ssl issuer:          C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Domain Validation Secure Server CA\n       Ssl starts at:       Oct  5 00:00:00 2016 GMT\n       Ssl subject:         OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.node-js-app.org\n       Ssl verified:        self signed.\n=====&gt; python-app\n       Ssl dir:             /home/dokku/python-app/tls\n       Ssl enabled:         false\n       Ssl hostnames:\n       Ssl expires at:\n       Ssl issuer:\n       Ssl starts at:\n       Ssl subject:\n       Ssl verified:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku certs:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app ssl information\n       Ssl dir:             /home/dokku/node-js-app/tls\n       Ssl enabled:         true\n       Ssl hostnames:       *.dokku.org dokku.org\n       Ssl expires at:      Oct  5 23:59:59 2019 GMT\n       Ssl issuer:          C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Domain Validation Secure Server CA\n       Ssl starts at:       Oct  5 00:00:00 2016 GMT\n       Ssl subject:         OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.dokku.org\n       Ssl verified:        self signed.\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku certs:report node-js-app --ssl-enabled\n</code></pre>"},{"location":"configuration/ssl/#hsts-header","title":"HSTS Header","text":"<p>The HSTS header is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. Dokku does enables this header by default for HTTPS requests.</p> <p>See the NGINX HSTS documentation for more information on how the HSTS configuration can be managed for your application.</p>"},{"location":"configuration/ssl/#http2-support","title":"HTTP/2 support","text":"<p>Certain versions of nginx have bugs that prevent HTTP/2 from properly responding to all clients, thus causing applications to be unavailable. For HTTP/2 to be enabled in your applications' nginx configs, you need to have installed nginx 1.11.5 or higher. See issue 2435 for more details.</p>"},{"location":"configuration/ssl/#ssl-port-exposure","title":"SSL Port Exposure","text":"<p>When your app is served from port <code>80</code> then the <code>/home/dokku/APP/nginx.conf</code> file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port <code>99999</code>) you may need to manually expose an ssl port via <code>dokku ports:add &lt;APP&gt; https:443:99999</code>.</p>"},{"location":"configuration/ssl/#other","title":"Other","text":""},{"location":"configuration/ssl/#running-behind-a-proxy-x-forwarded-ssl-etc","title":"Running behind a proxy (<code>X-Forwarded-Ssl</code>, etc.)","text":"<p>See the running behind another proxy documentation for more information on how to configure your Nginx config when your server is running behind a proxy (e.g. load balancer, etc.).</p>"},{"location":"deployment/application-deployment/","title":"Deploying an Application","text":"<p>Note</p> <p>This walkthrough uses the hostname <code>dokku.me</code> in commands. When deploying to your own server, you should substitute the domain <code>dokku.me</code> for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use <code>dokku.me</code> which points to the IP of the VM.</p>"},{"location":"deployment/application-deployment/#deploy-tutorial","title":"Deploy tutorial","text":"<p>Once you have configured Dokku with at least one user, you can deploy applications using <code>git push</code>. To quickly see Dokku deployment in action, try using the Heroku Ruby on Rails \"Getting Started\" app.</p> <pre><code># from your local machine\ngit clone https://github.com/heroku/ruby-getting-started\n</code></pre>"},{"location":"deployment/application-deployment/#create-the-app","title":"Create the app","text":"<p>SSH into the Dokku host and create the application as follows:</p> <pre><code># on the Dokku host\ndokku apps:create ruby-getting-started\n</code></pre>"},{"location":"deployment/application-deployment/#create-the-backing-services","title":"Create the backing services","text":"<p>Dokku by default does not provide datastores (e.g. MySQL, PostgreSQL) on a newly created app. You can add datastore support by installing plugins, and the Dokku project provides official plugins for common datastores.</p> <p>The Getting Started app requires a PostgreSQL service, so install the plugin and create the related service as follows:</p> <pre><code># on the Dokku host\n# install the postgres plugin\n# plugin installation requires root, hence the user change\nsudo dokku plugin:install https://github.com/dokku/dokku-postgres.git\n\n# create a postgres service with the name railsdatabase\ndokku postgres:create railsdatabase\n</code></pre> <p>Each service may take a few moments to create.</p>"},{"location":"deployment/application-deployment/#linking-backing-services-to-applications","title":"Linking backing services to applications","text":"<p>Once the services have been created, you then set the <code>DATABASE_URL</code> environment variable by linking the service, as follows:</p> <pre><code># on the Dokku host\n# each official datastore offers a `link` method to link a service to any application\ndokku postgres:link railsdatabase ruby-getting-started\n</code></pre> <p>Dokku supports linking a single service to multiple applications as well as linking only one service per application.</p>"},{"location":"deployment/application-deployment/#deploy-the-app","title":"Deploy the app","text":"<p>Warning</p> <p>Your app should respect the <code>PORT</code> environment variable, otherwise it may not respond to web requests. You can find more information in the port management documentation.**</p> <p>Now you can deploy the <code>ruby-getting-started</code> app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.</p> <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\ncd ruby-getting-started\ngit remote add dokku dokku@dokku.me:ruby-getting-started\ngit push dokku main\n</code></pre> <p>Note</p> <p>Some tools may not support the short-upstream syntax referenced above, and you may need to prefix the upstream with the scheme <code>ssh://</code> like so: <code>ssh://dokku@dokku.me:ruby-getting-started</code> Please see the Git documentation for more details.</p> <p>Note</p> <p>Your private key should be registered with <code>ssh-agent</code> in your local development environment. If you get a <code>permission denied</code> error when pushing, you can register your private key as follows: <code>ssh-add -k ~/&lt;your private key&gt;</code>.</p> <p>After running <code>git push dokku main</code>, you should have output similar to this in your terminal:</p> <pre><code>Counting objects: 231, done.\nDelta compression using up to 8 threads.\nCompressing objects: 100% (162/162), done.\nWriting objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done.\nTotal 231 (delta 93), reused 147 (delta 53)\n-----&gt; Cleaning up...\n-----&gt; Building ruby-getting-started from herokuish...\n-----&gt; Adding BUILD_ENV to build environment...\n-----&gt; Ruby app detected\n-----&gt; Compiling Ruby/Rails\n-----&gt; Using Ruby version: ruby-2.2.1\n-----&gt; Installing dependencies using 1.9.7\n       Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment\n       Fetching gem metadata from https://rubygems.org/...........\n       Fetching version metadata from https://rubygems.org/...\n       Fetching dependency metadata from https://rubygems.org/..\n       Using rake 10.4.2\n\n...\n\n=====&gt; Application deployed:\n       http://ruby-getting-started.dokku.me\n</code></pre> <p>Once the deploy is complete, the application's web URL will be generated as above.</p> <p>Dokku supports deploying applications in a few ways:</p> <ul> <li>Heroku buildpacks via Herokuish: See the herokuish buildpacks documentation to learn about the different ways to specify a buildpack.<ul> <li>This is the default method used by Dokku.</li> </ul> </li> <li>Dockerfile: See the dockerfile documentation to learn about the different ways to configure Dockerfile-based deploys.</li> <li>Docker Image: See the docker image documentation to learn about how to deploy a Docker Image.</li> </ul>"},{"location":"deployment/application-deployment/#setting-up-ssl","title":"Setting up SSL","text":"<p>Info</p> <p>While SSL certificates can be imported, automated SSL via Letsencrypt requires that all domains on an app correctly point at your server's public ip address. Please keep this in mind when using Letsencrypt.</p> <p>For many users, responding to requests via <code>https</code> will be desirable. Dokku has a complete ssl plugin built in that can be used to import SSL certificates (below is a short example, please refer to the ssl documentation for more information):</p> <pre><code>dokku certs:add ruby-getting-started server.crt server.key\n</code></pre> <p>As an alternative, the Dokku project offers an optional letsencrypt plugin that can be used to automate SSL certificate retrieval and renewal.</p> <pre><code># on the Dokku host\n# install the letsencrypt plugin\n# plugin installation requires root, hence the user change\nsudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git\n\n# set global email for letsencrypt\ndokku letsencrypt:set --global email your-email@your.domain.com\n\n# set a custom domain that you own for your application\ndokku domains:set ruby-getting-started ruby-getting-started.your.domain.com\n\n# enable letsencrypt\ndokku letsencrypt:enable ruby-getting-started\n\n# enable auto-renewal\ndokku letsencrypt:cron-job --add\n</code></pre>"},{"location":"deployment/application-deployment/#skipping-deployment","title":"Skipping deployment","text":"<p>If you only want to rebuild and tag a container, you can skip the deployment phase by setting <code>$DOKKU_SKIP_DEPLOY</code> to <code>true</code> by running:</p> <pre><code># on the Dokku host\ndokku config:set ruby-getting-started DOKKU_SKIP_DEPLOY=true\n</code></pre>"},{"location":"deployment/application-deployment/#redeploying-or-restarting","title":"Redeploying or restarting","text":"<p>If you need to redeploy or restart your app:</p> <pre><code># on the Dokku host\ndokku ps:rebuild ruby-getting-started\n</code></pre> <p>See the process scaling documentation for more information on how to manage your app processes.</p>"},{"location":"deployment/application-deployment/#deploying-with-private-git-submodules","title":"Deploying with private Git submodules","text":"<p>Dokku uses Git locally (i.e. not a Docker image) to build its own copy of your app repo, including submodules, as the <code>dokku</code> user. This means that in order to deploy private Git submodules, you need to put your deploy key in <code>/home/dokku/.ssh/</code> and potentially add <code>github.com</code> (or your VCS host key) into <code>/home/dokku/.ssh/known_hosts</code>. You can use the following test to confirm your setup is correct:</p> <pre><code># on the Dokku host\nsu - dokku\nssh-keyscan -t rsa github.com &gt;&gt; ~/.ssh/known_hosts\nssh -T git@github.com\n</code></pre> <p>Warning</p> <p>if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply.</p>"},{"location":"deployment/application-deployment/#deploying-to-subdomains","title":"Deploying to subdomains","text":"<p>If you do not enter a fully qualified domain name when pushing your app, Dokku deploys the app to <code>&lt;remotename&gt;.yourdomain.tld</code> as follows:</p> ShellOutput <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\n# the below example assumes your app server domain or IP is dokku.me. Push in the form of: dokku@{serveripordomain}:{dokkuappname}\ngit remote add dokku dokku@dokku.me:ruby-getting-started\ngit push dokku main\n</code></pre> <pre><code>remote: -----&gt; Application deployed:\nremote:        http://ruby-getting-started.dokku.me\n</code></pre> <p>You can also specify the fully qualified name as follows:</p> ShellOutput <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\ngit remote add dokku dokku@dokku.me:app.dokku.me\ngit push dokku main\n</code></pre> <pre><code>remote: -----&gt; Application deployed:\nremote:        http://app.dokku.me\n</code></pre> <p>This is useful when you want to deploy to the root domain:</p> ShellOutput <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\ngit remote add dokku dokku@dokku.me:dokku.me\ngit push dokku main\n</code></pre> <pre><code>... deployment ...\n\nremote: -----&gt; Application deployed:\nremote:        http://dokku.me\n</code></pre>"},{"location":"deployment/application-deployment/#dokkudocker-container-management-compatibility","title":"Dokku/Docker container management compatibility","text":"<p>Dokku is, at its core, a Docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the Docker daemon.</p> <p>Prior to every deployment, Dokku will execute a cleanup function. As of 0.5.x, the cleanup removes all containers with the <code>dokku</code> label where the status is either <code>dead</code> or <code>exited</code> (previous versions would remove all <code>dead</code> or <code>exited</code> containers). The cleanup function also removes all images with <code>dangling</code> status.</p>"},{"location":"deployment/application-deployment/#adding-deploy-users","title":"Adding deploy users","text":"<p>See the user management documentation for more information on how to manage users with access to your Dokku server.</p>"},{"location":"deployment/application-deployment/#default-vhost","title":"Default vhost","text":"<p>See the domains documentation for more information on how to manage the default site.</p>"},{"location":"deployment/application-deployment/#deploying-non-master-branch","title":"Deploying non-master branch","text":"<p>See the Git documentation for more information on deploying a non-master branch to your application.</p>"},{"location":"deployment/application-deployment/#dockerfile-deployment","title":"Dockerfile deployment","text":"<p>See the Dockerfile documentation for information Dokku's Dockerfile support.</p>"},{"location":"deployment/application-deployment/#image-tagging","title":"Image tagging","text":"<p>See the image tagging documentation for more information on how Docker images can be tagged and deployed for a given application.</p>"},{"location":"deployment/application-deployment/#specifying-a-custom-buildpack","title":"Specifying a custom buildpack","text":"<p>See the herokuish buildpack documentation for more information on how to specify a set of custom buildpacks for your application.</p>"},{"location":"deployment/application-deployment/#removing-a-deployed-app","title":"Removing a deployed app","text":"<p>See the application management documentation for more information on how to remove an application from your Dokku server.</p>"},{"location":"deployment/application-deployment/#renaming-a-deployed-app","title":"Renaming a deployed app","text":"<p>See the application management documentation for more information on how an application can be renamed and the impact of doing so upon the application and associated resources.</p>"},{"location":"deployment/application-deployment/#zero-downtime-deploy","title":"Zero downtime deploy","text":"<p>See the zero-downtime deploy documentation for more information on how Dokku enables zero-downtime deploys.</p>"},{"location":"deployment/application-management/","title":"Application Management","text":"<p>New</p> <p>Introduced in 0.3.1</p> <pre><code>apps:clone &lt;old-app&gt; &lt;new-app&gt;                 # Clones an app\napps:create &lt;app&gt;                              # Create a new app\napps:destroy &lt;app&gt;                             # Permanently destroy an app\napps:exists &lt;app&gt;                              # Checks if an app exists\napps:list                                      # List your apps\napps:lock &lt;app&gt;                                # Locks an app for deployment\napps:locked &lt;app&gt;                              # Checks if an app is locked for deployment\napps:rename &lt;old-app&gt; &lt;new-app&gt;                # Rename an app\napps:report [&lt;app&gt;] [&lt;flag&gt;]                   # Display report about an app\napps:unlock &lt;app&gt;                              # Unlocks an app for deployment\n</code></pre>"},{"location":"deployment/application-management/#usage","title":"Usage","text":""},{"location":"deployment/application-management/#listing-applications","title":"Listing applications","text":"<p>New</p> <p>Introduced in 0.8.1. Use the <code>apps</code> command for older versions.</p> <p>You can easily list all available applications using the <code>apps:list</code> command:</p> ShellOutput <pre><code>dokku apps:list\n</code></pre> <pre><code>=====&gt; My Apps\nnode-js-app\npython-app\n</code></pre> <p>Note that you can easily hide extra output from Dokku commands by using the <code>--quiet</code> flag, which makes it easier to parse on the command line.</p> ShellOutput <pre><code>dokku --quiet apps:list\n</code></pre> <pre><code>node-js-app\npython-app\n</code></pre>"},{"location":"deployment/application-management/#checking-if-an-application-exists","title":"Checking if an application exists","text":"<p>For CI/CD pipelines, it may be useful to see if an application exists before creating a \"review\" application for a specific branch. You can do so via the <code>apps:exists</code> command:</p> ShellOutput <pre><code>dokku apps:exists  node-js-app\n</code></pre> <pre><code>App does not exist\n</code></pre> <p>The <code>apps:exists</code> command will return non-zero if the application does not exist, and zero if it does.</p>"},{"location":"deployment/application-management/#manually-creating-an-application","title":"Manually creating an application","text":"<p>A common pattern for deploying applications to Dokku is to configure an application before deploying it. You can do so via the <code>apps:create</code> command:</p> ShellOutput <pre><code>dokku apps:create node-js-app\n</code></pre> <pre><code>Creating node-js-app... done\n</code></pre> <p>Once created, you can configure the application as normal, and deploy the application whenever ready. This is useful for cases where you may wish to do any of the following kinds of tasks:</p> <ul> <li>Configure domain names and SSL certificates.</li> <li>Create and link datastores.</li> <li>Set environment variables.</li> </ul>"},{"location":"deployment/application-management/#removing-a-deployed-app","title":"Removing a deployed app","text":"<p>In some cases, you may need to destroy an application, whether it is because the application is temporary or because it was misconfigured. In these cases, you can use the <code>apps:destroy</code> command. Performing any destructive actions in Dokku requires confirmation, and this command will ask for the name of the application being deleted before doing so.</p> ShellOutput <pre><code>dokku apps:destroy node-js-app\n</code></pre> <pre><code> !     WARNING: Potentially Destructive Action\n !     This command will destroy node-js-app (including all add-ons).\n !     To proceed, type \"node-js-app\"\n\nDestroying node-js-app (including all add-ons)\n</code></pre> <p>Info</p> <p>node-js-app</p> <p>This will prompt you to verify the application's name before destroying it. You may also use the <code>--force</code> flag to circumvent this verification process:</p> ShellOutput <pre><code>dokku --force apps:destroy node-js-app\n</code></pre> <pre><code>Destroying node-js-app (including all add-ons)\n</code></pre> <p>The <code>--force</code> flag can also be specified on the command vs globally:</p> ShellOutput <pre><code>dokku apps:destroy --force node-js-app\n</code></pre> <pre><code>Destroying node-js-app (including all add-ons)\n</code></pre> <p>Destroying an application will unlink all linked services and destroy any config related to the application. Note that linked services will retain their data for later use (or removal).</p>"},{"location":"deployment/application-management/#renaming-a-deployed-app","title":"Renaming a deployed app","text":"<p>New</p> <p>Introduced in 0.4.7</p> <p>You can rename a deployed app using the <code>apps:rename</code> command. Note that the application must have been deployed at least once, or the rename will not complete successfully:</p> ShellOutput <pre><code>dokku apps:rename node-js-app io-js-app\n</code></pre> <pre><code>Destroying node-js-app (including all add-ons)\n-----&gt; Cleaning up...\n-----&gt; Building io-js-app from herokuish...\n-----&gt; Adding BUILD_ENV to build environment...\n-----&gt; Node.js app detected\n\n-----&gt; Creating runtime environment\n\n...\n\n=====&gt; Application deployed:\n       http://io-js-app.ci.dokku.me\n\nRenaming node-js-app to io-js-app... done\n</code></pre> <p>This will copy all of your app's contents into a new app directory with the name of your choice, delete your old app, then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved.</p> <p>By default, Dokku will deploy the renamed app, though you can skip the deploy by using the <code>--skip-deploy</code> flag:</p> <pre><code>dokku apps:rename --skip-deploy node-js-app io-js-app\n</code></pre> <p>Remember to also change your git remote on your local machine in order to make <code>git push dokku main</code> work again. For this you can use <code>git remote set-url</code>.</p> <pre><code>git remote set-url dokku dokku@dokku.me:io-js-app\n</code></pre>"},{"location":"deployment/application-management/#cloning-an-existing-app","title":"Cloning an existing app","text":"<p>New</p> <p>Introduced in 0.11.5</p> <p>You can clone an existing app using the <code>apps:clone</code> command.  Note that the application must have been deployed at least once, or cloning will not complete successfully:</p> ShellOutput <pre><code>dokku apps:clone node-js-app io-js-app\n</code></pre> <pre><code>Cloning node-js-app to io-js-app... done\n</code></pre> <p>This will copy all of your app's contents into a new app directory with the name of your choice and then rebuild the new version of the app and deploy it with the following caveats:</p> <ul> <li>All of your environment variables, including database urls, will be preserved.</li> <li>Custom domains are not applied to the new app.</li> <li>SSL certificates will not be copied to the new app.</li> <li>Port mappings with the scheme <code>https</code> and host-port <code>443</code> will be skipped.</li> </ul> <p>Warning</p> <p>If you have exposed specific ports via <code>docker-options</code> plugin, or performed anything that cannot be done against multiple applications, <code>apps:clone</code> may result in errors.</p> <p>By default, Dokku will deploy this new app, though you can skip the deploy by using the <code>--skip-deploy</code> flag:</p> <pre><code>dokku apps:clone --skip-deploy node-js-app io-js-app\n</code></pre> <p>Finally, if the application already exists, you may wish to ignore errors resulting from attempting to clone over it. To do so, you can use the <code>--ignore-existing</code> flag. A warning will be emitted, but the command will return <code>0</code>.</p> <pre><code>dokku apps:clone --ignore-existing node-js-app io-js-app\n</code></pre>"},{"location":"deployment/application-management/#locking-app-deploys","title":"Locking app deploys","text":"<p>New</p> <p>Introduced in 0.11.6</p> <p>If you wish to disable deploying for a period of time, this can be done via deploy locks. Normally, deploy locks exist only for the duration of a deploy so as to avoid deploys from colliding, but a deploy lock can be created by running the <code>apps:lock</code> command.</p> ShellOutput <pre><code>dokku apps:lock node-js-app\n</code></pre> <pre><code>-----&gt; Deploy lock created\n</code></pre>"},{"location":"deployment/application-management/#unlocking-app-deploys","title":"Unlocking app deploys","text":"<p>New</p> <p>Introduced in 0.11.6</p> <p>In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the <code>apps:unlock</code> command.</p> <p>Warning</p> <p>Removing the deploy lock will not stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.</p> ShellOutput <pre><code>dokku apps:unlock node-js-app\n</code></pre> <pre><code> !     A deploy may be in progress.\n !     Removing the app lock will not stop in progress deploys.\n-----&gt; Deploy lock removed.\n</code></pre>"},{"location":"deployment/application-management/#checking-lock-status","title":"Checking lock status","text":"<p>New</p> <p>Introduced in 0.13.0</p> <p>In some cases, you may wish to inspect the state of an app lock. To do so, you can issue an <code>apps:lock</code> command. This will exit non-zero if there is no app lock in place.</p> ShellOutput <pre><code>dokku apps:locked node-js-app\n</code></pre> <pre><code>Deploy lock does not exist\n</code></pre>"},{"location":"deployment/application-management/#displaying-reports-for-an-app","title":"Displaying reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the deployed apps using the <code>apps:report</code> command:</p> ShellOutput <pre><code>dokku apps:report\n</code></pre> <pre><code>=====&gt; node-js-app app information\n       App created at:              1635126111\n       App dir:                     /home/dokku/node-js-app\n       App deploy source:           git\n       App deploy source metadata:  cd7b8afccb202f222e7dc7b427553e71ba5ddafd\n       App locked:                  false\n=====&gt; python-sample app information\n       App created at:              1635126000\n       App dir:                     /home/dokku/python-sample\n       App deploy source:\n       App deploy source metadata:\n       App locked:                  false\n=====&gt; ruby-sample app information\n       App created at:              1635122462\n       App dir:                     /home/dokku/ruby-sample\n       App deploy source:           git\n       App deploy source metadata:  c60921ea2799ca108276414b95ea197f16798d51\n       App locked:                  false\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku apps:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app app information\n       App dir:                     /home/dokku/node-js-app\n       App deploy source:           git\n       App deploy source metadata:  cd7b8afccb202f222e7dc7b427553e71ba5ddafd\n       App locked:                  false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku apps:report node-js-app --app-dir\n</code></pre>"},{"location":"deployment/logs/","title":"Log Management","text":"<pre><code>logs &lt;app&gt; [-h|--help] [-t|--tail] [-n|--num num] [-q|--quiet] [-p|--ps process]  # Display recent log output\nlogs:failed --all|&lt;app&gt;                                                    # Shows the last failed deploy logs\nlogs:report [&lt;app&gt;] [&lt;flag&gt;]                                               # Displays a logs report for one or more apps\nlogs:set [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt;                                    # Set or clear a logs property for an app\nlogs:vector-logs [--num num] [--tail]                                      # Display vector log output\nlogs:vector-start                                                          # Start the vector logging container\nlogs:vector-stop                                                           # Stop the vector logging container\n</code></pre>"},{"location":"deployment/logs/#usage","title":"Usage","text":""},{"location":"deployment/logs/#application-logs","title":"Application logs","text":"<p>You can easily get logs of an app using the <code>logs</code> command:</p> <pre><code>dokku logs node-js-app\n</code></pre> <p>Logs are pulled via integration with the scheduler for the specified application via \"live tailing\". As such, logs from previously running deployments are usually not available. Users that desire to see logs from previous deployments for debugging purposes should persist those logs to external services. Please see Dokku's vector integration for more information on how to persist logs across deployments to ship logs to another service or a third-party platform.</p>"},{"location":"deployment/logs/#behavioral-modifiers","title":"Behavioral modifiers","text":"<p>Dokku also supports certain command-line arguments that augment the <code>log</code> command's behavior.</p> <pre><code>-n, --num NUM        # the number of lines to display\n-p, --ps PS          # only display logs from the given process\n-t, --tail           # continually stream logs\n-q, --quiet          # display raw logs without colors, time and names\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku logs node-js-app -t -p web\n</code></pre> <p>The above command will show logs continually from the web process.</p>"},{"location":"deployment/logs/#failed-deploy-logs","title":"Failed deploy logs","text":"<p>Warning</p> <p>The default docker-local scheduler will \"store\" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.</p> <p>In some cases, it may be useful to retrieve the logs from a previously failed deploy.</p> <p>You can retrieve these logs by using the <code>logs:failed</code> command.</p> <pre><code>dokku logs:failed node-js-app\n</code></pre> <p>You may also fetch all failed app logs by using the <code>--all</code> flag.</p> <pre><code>dokku logs:failed --all\n</code></pre>"},{"location":"deployment/logs/#docker-log-retention","title":"Docker Log Retention","text":"<p>Docker log retention can be specified via the <code>logs:set</code> command by specifying a value for <code>max-size</code>. Log retention is set via injected docker options for all applications, but is also available via the <code>logs-get-property</code> trigger for alternative schedulers.</p> <pre><code>dokku logs:set node-js-app max-size 20m\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku logs:set node-js-app max-size\n</code></pre> <p>Valid values include any integer number followed by a unit of measure (<code>k</code>, <code>m</code>, or <code>g</code>) or the string <code>unlimited</code>. Setting to <code>unlimited</code> will result in Dokku omitting the log option.</p> <p>The <code>max-size</code> property can also be set globally. The global default is <code>10m</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku logs:set --global max-size 20m\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku logs:set --global max-size\n</code></pre>"},{"location":"deployment/logs/#vector-logging-shipping","title":"Vector Logging Shipping","text":"<p>New</p> <p>Introduced in 0.22.6</p> <p>Vector is an open-source, lightweight and ultra-fast tool for building observability pipelines. Dokku integrates with it for shipping container logs for the <code>docker-local</code> scheduler. Users may configure log-shipping on a per-app or global basis, neither of which interfere with the <code>dokku logs</code> commands.</p>"},{"location":"deployment/logs/#starting-the-vector-container","title":"Starting the Vector container","text":"<p>Warning</p> <p>While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected.</p> <p>Vector may be started via the <code>logs:vector-start</code> command.</p> <pre><code>dokku logs:vector-start\n</code></pre> <p>This will start a new container named <code>vector</code> with Dokku's vector config mounted and ready for use. If a running container already exists, this command will do nothing. Additionally, if a container exists but is not running, this command will attempt to start the container.</p> <p>While the default vector image is hardcoded, users may specify an alternative via the <code>--vector-image</code> flag:</p> <pre><code>dokku logs:vector-start --vector-image timberio/vector:latest-debian\n</code></pre> <p>The <code>vector</code> container will be started with the following volume mounts:</p> <ul> <li><code>/var/lib/dokku/data/logs/vector.json:/etc/vector/vector.json</code></li> <li><code>/var/run/docker.sock:/var/run/docker.sock</code></li> <li><code>/var/log/dokku/apps:/var/log/dokku/apps</code></li> </ul> <p>The final volume mount - <code>/var/log/dokku/apps</code> - may be used for users that wish to ship logs to a file on disk that may be later logrotated. This directory is owned by the <code>dokku</code> user and group, with permissions set to <code>0755</code>. At this time, log-rotation is not configured for this directory.</p>"},{"location":"deployment/logs/#stopping-the-vector-container","title":"Stopping the Vector container","text":"<p>Vector may be stopped via the <code>logs:vector-stop</code> command.</p> <pre><code>dokku logs:vector-stop\n</code></pre> <p>The <code>vector</code> container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"deployment/logs/#checking-vectors-logs","title":"Checking Vector's Logs","text":"<p>It may be necessary to check the vector container's logs to ensure that vector is operating as expected. This can be performed with the <code>logs:vector-logs</code> command.</p> <pre><code>dokku logs:vector-logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku logs:vector-logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the vector container, with an initial history of 10 log lines</p>"},{"location":"deployment/logs/#configuring-a-log-sink","title":"Configuring a log sink","text":"<p>Vector uses the concept of log \"sinks\" to send logs to a given endpoint. Log sinks may be configured globally or on a per-app basis by specifying a <code>vector-sink</code> in DSN form with the <code>logs:set</code> command. Specifying a sink value will reload any running vector container.</p> <pre><code># setting the sink value in quotes is encouraged to avoid\n# issues with ampersand encoding in shell commands\ndokku logs:set node-js-app vector-sink \"console://?encoding[codec]=json\"\n</code></pre> <p>A sink may be removed by setting an empty value, which will also reload the running vector container.</p> <pre><code>dokku logs:set node-js-app vector-sink\n</code></pre> <p>Only one sink may be specified on a per-app basis at a given time.</p> <p>Log sinks can also be specified globally by specifying the <code>--global</code> flag to <code>logs:set</code> with no app name specified:</p> <pre><code>dokku logs:set --global vector-sink \"console://?encoding[codec]=json\"\n</code></pre> <p>As with app-specific sink settings, the global value may also be cleared by setting no value.</p> <pre><code>dokku logs:set --global vector-sink\n</code></pre>"},{"location":"deployment/logs/#log-sink-dsn-format","title":"Log Sink DSN Format","text":"<p>The DSN form of a sink is as follows:</p> <pre><code>SINK_TYPE://?SINK_OPTIONS\n</code></pre> <p>Valid values for <code>SINK_TYPE</code> include all log vector log sinks, while <code>SINK_OPTIONS</code> is a query-string form for the sink's options. The following is a short description on how to set various values:</p> <ul> <li><code>bool</code>: form: <code>key=bool</code></li> <li><code>string</code>: form: <code>key=string</code></li> <li><code>int</code>: form: <code>key=int</code></li> <li><code>[string]</code>: form: <code>key[]=string</code></li> <li><code>[int]</code>: form: <code>key[]=int</code></li> <li><code>table</code>: form: <code>option[key]=value</code></li> </ul> <p>For some sinks - such as the <code>http</code> sink - it may be useful to use special characters such as <code>&amp;</code>. These characters must be url escaped as per RFC 3986.</p> <pre><code># the following command will set the `http` sink with a uri config value\n# for a uri config value: https://loggerservice.com:1234/?token=abc1234&amp;type=vector\n# the url quoted version: https%3A//loggerservice.com%3A1234/%3Ftoken%3Dabc1234%26type%3Dvector\ndokku logs:set test vector-sink \"http://?uri=https%3A//loggerservice.com%3A1234/%3Ftoken%3Dabc1234%26type%3Dvector\"\n</code></pre> <p>Please read the sink documentation for your sink of choice to configure the sink as desired.</p>"},{"location":"deployment/remote-commands/","title":"Remote Commands","text":"<p>Dokku commands can be run over SSH. Anywhere you would run <code>dokku &lt;command&gt;</code>, just run <code>ssh -t dokku@dokku.me &lt;command&gt;</code> The <code>-t</code> is used to request a pty. It is highly recommended to do so. To avoid the need to type the <code>-t</code> option each time, create/modify a section in the <code>.ssh/config</code> on the client side, as follows:</p> <pre><code>Host dokku.me\n    RequestTTY yes\n</code></pre>"},{"location":"deployment/remote-commands/#behavioral-modifiers","title":"Behavioral modifiers","text":"<p>Dokku also supports certain command line arguments that augment its behavior. If using these over SSH, you must use the form <code>ssh -t dokku@dokku.me -- &lt;command&gt;</code> to avoid SSH interpreting Dokku arguments for itself.</p> <pre><code>--quiet                suppress output headers\n--trace                enable DOKKU_TRACE for current execution only\n--force                force flag. currently used in apps:destroy and other \":destroy\" commands\n</code></pre>"},{"location":"deployment/remote-commands/#official-client","title":"Official Client","text":"<p>You may optionally use the official client when connecting to the Dokku server.</p> <p>Of all methods, this is the most official method of interacting with your Dokku installation. It is a bash script that interacts with a remote Dokku installation via <code>ssh</code>. It is available in <code>contrib/dokku_client.sh</code> in the root of the Dokku repository.</p> <p>It can be installed either via the Homebrew package manager (macOS only), or manually.</p>"},{"location":"deployment/remote-commands/#installation-via-homebrew","title":"Installation via Homebrew","text":"<p>To install, simply run the following command:</p> <pre><code>brew install dokku/repo/dokku\n</code></pre>"},{"location":"deployment/remote-commands/#manual-installation","title":"Manual installation","text":"<p>To install manually, simply clone the Dokku repository down and add the <code>dokku</code> alias pointing at the script:</p> <pre><code>git clone git@github.com:dokku/dokku.git ~/.dokku\n\n# optional: make sure that the dokku_client.sh version matches your Dokku version\ncd ~/.dokku\ngit checkout &lt;tag/branch&gt;\n\n# add the following to either your\n# .bashrc, .bash_profile, or .profile file\nalias dokku='$HOME/.dokku/contrib/dokku_client.sh'\n</code></pre> <p>Alternatively, if using another shell such as zsh, create an alias command which invokes the script using bash:</p> <pre><code># zsh: add the following to either .zshenv or .zshrc\nalias dokku='bash $HOME/.dokku/contrib/dokku_client.sh'\n\n# fish: add the following to ~/.config/fish/config.fish\nalias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh'\n\n# csh: add the following to .cshrc\nalias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh'\n</code></pre>"},{"location":"deployment/remote-commands/#usage","title":"Usage","text":"<p>All commands have the application name automatically set via the <code>--app</code> flag on the remote server, and thus the app name does not need to be specified manually for core plugins.</p> <p>The client supports several environment variables:</p> <ul> <li><code>DOKKU_HOST</code> (default: <code>dokku</code> git remote): Used to interact with a specific remote server. Can be overridden via the <code>--remote</code> flag.</li> <li><code>DOKKU_PORT</code> (default: <code>22</code>): Used to specify a port to connect to the Dokku server on.</li> </ul> <p>It also supports several flags (all flags unspecified here are passed as is to the server):</p> <ul> <li><code>--app</code>: Override the remote app in use.</li> <li><code>--trace</code>: Enable trace mode.</li> <li><code>--remote</code>: Override the remote server.</li> <li><code>--global</code>: Unsets the \"app\" value. May not be supported for the specified command.</li> </ul> <p>In addition, the following commands have special local side-effects:</p> <ul> <li><code>apps:create</code>:<ul> <li>If no local <code>--app</code> flag is specified or detected from a <code>dokku</code> git remote, a random name is generated and used for the app.</li> <li>The <code>dokku</code> git remote is set if not already set.</li> </ul> </li> <li><code>apps:destroy</code>:<ul> <li>Removes the local <code>dokku</code> git remote if set.</li> </ul> </li> </ul>"},{"location":"deployment/remote-commands/#specifying-a-remote","title":"Specifying a remote","text":"<p>While many users will only ever push to a single dokku remote from a given repository, it may be useful to point the same repository at multiple remotes, especially in the case of pre-production environments. This can be done via the <code>remote</code> commands. These commands are only available within the official remote client, and are not server-side commands.</p> <p>To see your currently configured remote, run <code>dokku remote</code>. This will respect the <code>--remote</code> flag.</p> <p>To list all available remotes, run <code>dokku remote:list</code>. This is equivalent to running <code>git remote</code>.</p> <p>To add a remote, run <code>dokku remote:add $REMOTE_NAME dokku@dokku.me:$APP_NAME</code>, replacing <code>$REMOTE_NAME</code> with your desired remote name, the <code>$APP_NAME</code> with your desired app name and the host <code>dokku.me</code> with your Dokku host. This is equivalent to running <code>git remote add $REMOTE_NAME dokku@dokku.me:$APP_NAME</code>.</p> <p>To remove a remote, run <code>dokku remote:remove $REMOTE_NAME</code>. This is equivalent to running <code>git remote remove $REMOTE_NAME</code>.</p> <p>By default, the remote in use is <code>dokku</code>. To change the remote the client uses by default, run <code>dokku remote:set $REMOTE_NAME</code>, where <code>$REMOTE_NAME</code> is the name of your desired remote. This will not check the value specified, so that remote must be available or errors will occur when running normal client commands. Note that specifying <code>--remote</code> when running dokku commands will override this configuration value.</p> <p>To clear the configured remote, run <code>dokku remote:unset</code>. The client will unset the configured remote, and will default back to <code>dokku</code>, or the value of <code>--remote</code> if specified.</p>"},{"location":"deployment/remote-commands/#unofficial-clients","title":"Unofficial Clients","text":"<p>Please refer to the community clients list for more details.</p>"},{"location":"deployment/user-management/","title":"User Management","text":"<p>New</p> <p>Introduced in 0.7.0</p> <pre><code>ssh-keys:add &lt;name&gt; [/path/to/key]                 # Add a new public key by pipe or path\nssh-keys:list [--format text|json] [&lt;name&gt;]        # List of all authorized Dokku public ssh keys\nssh-keys:remove [--fingerprint fingerprint|&lt;name&gt;] # Remove SSH public key by name\n</code></pre> <p>When pushing to Dokku, SSH key-based authorization is the preferred authentication method, for ease of use and increased security.</p> <p>Users in Dokku are managed via the <code>~/dokku/.ssh/authorized_keys</code> file. It is highly recommended that you follow the steps below to manage users on a Dokku server.</p> <p>Info</p> <p>Users of older versions of Dokku may use the <code>sshcommand</code> binary to manage keys instead of the <code>ssh-keys</code> plugin. Please refer to the Dokku documentation for your version for more details.</p>"},{"location":"deployment/user-management/#usage","title":"Usage","text":""},{"location":"deployment/user-management/#listing-ssh-keys","title":"Listing SSH keys","text":"<p>You can use the <code>ssh-keys:list</code> command to show all configured SSH keys.</p> ShellOutput <pre><code>dokku ssh-keys:list\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc NAME=\"admin\" SSHCOMMAND_ALLOWED_KEYS=\"no-agent-forwarding,no-user-rc,no-X11-forwarding,no-port-forwarding\"\n</code></pre> <p>The output contains the following information:</p> <ul> <li>SSH Key Fingerprint.</li> <li>The <code>KEY_NAME</code>.</li> <li>A comma separated list of SSH options under the <code>SSHCOMMAND_ALLOWED_KEYS</code> name.</li> </ul> <p>New</p> <p>Introduced in 0.20.2</p> <p>The keys for a specific user may be listed by specifying a second argument to the <code>ssh-keys:list</code> command:</p> <pre><code>dokku ssh-keys:list admin\n</code></pre> <p>New</p> <p>Introduced in 0.22.3</p> <p>The output format may be specified via the <code>--format</code> flag. Supported values include <code>json</code> and <code>text</code>.</p> <pre><code>dokku ssh-keys:list --format json\n</code></pre> <p>This can additionally be used to filter to keys for a particular user:</p> <pre><code>dokku ssh-keys:list --format json admin\n</code></pre>"},{"location":"deployment/user-management/#adding-ssh-keys","title":"Adding SSH keys","text":"<p>You can add your public key to Dokku with the <code>ssh-keys:add</code> command. The path specified must contain your desired public ssh key contents and must exist on the server. Any special characters - such as <code>~</code> - are interpreted under the <code>dokku</code> user context. The output will be the fingerprint of the SSH key:</p> ShellOutput <pre><code>dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc\n</code></pre> <p><code>KEY_NAME</code> is the name you want to use to refer to this particular key. Including the word <code>admin</code> in the name will grant the user privileges to add additional keys remotely.</p> <p>Info</p> <p><code>KEY_NAME</code> is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The SSH (Git) user is always <code>dokku</code>, as this is the system user that the <code>dokku</code> binary uses to perform all its actions.</p> <p>Alternatively, you may pipe the contents of your ssh key via <code>cat</code> or <code>echo</code> into the <code>ssh-keys:add</code> command instead of specifying a path to the ssh key:</p> ShellOutputShellOutput <pre><code>echo \"$CONTENTS_OF_YOUR_PUBLIC_SSH_KEY_HERE\" | dokku ssh-keys:add KEY_NAME\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc\n</code></pre> <pre><code>cat path/to/id_rsa.pub | dokku ssh-keys:add KEY_NAME\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc\n</code></pre> <p>Admin users and root can add keys remotely by specifying the <code>dokku</code> bin on their <code>ssh</code> command:</p> <pre><code>cat ~/.ssh/id_rsa.pub | ssh root@dokku.me dokku ssh-keys:add KEY_NAME\n</code></pre> <p>If you are using the Vagrant installation, you can also use the <code>make vagrant-acl-add</code> target to add your public key to Dokku (it will use your host username as the <code>USER</code>):</p> <pre><code>cat ~/.ssh/id_rsa.pub | make vagrant-acl-add\n</code></pre>"},{"location":"deployment/user-management/#removing-ssh-keys","title":"Removing SSH keys","text":"<p>As key names are unique, they can be used to remove a public SSH key.</p> <pre><code>dokku ssh-keys:remove KEY_NAME\n</code></pre> <p>An SSH Key can also be removed by fingerprint.</p> <pre><code>dokku ssh-keys:remove --fingerprint FINGERPRINT\n</code></pre>"},{"location":"deployment/user-management/#scoping-commands-to-specific-users","title":"Scoping commands to specific users","text":"<p>Support for scoping commands to specific users can be added through plugins that take advantage of the user-auth plugin trigger to handle command authorization. See also the list of community-provided plugins.</p>"},{"location":"deployment/user-management/#granting-other-unix-user-accounts-dokku-access","title":"Granting other Unix user accounts Dokku access","text":"<p>Any Unix user account which belongs to the <code>sudo</code> Unix group can run Dokku.  However, you may want to give them Dokku access but not full sudo privileges.</p> <p>To allow other Unix user accounts to be able to run Dokku commands, without giving them full sudo access, modify your sudoers configuration.</p> <p>Use <code>visudo /etc/sudoers.d/dokku-users</code>, or <code>visudo /etc/sudoers</code> to add the following line:</p> <pre><code>%dokku ALL=(ALL:ALL) NOPASSWD:SETENV: /usr/bin/dokku\n</code></pre>"},{"location":"deployment/zero-downtime-deploys/","title":"Zero Downtime Deploy Checks","text":"<p>New</p> <p>Introduced in 0.5.0</p> <pre><code>checks:disable &lt;app&gt; [process-type(s)]    Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments***\nchecks:enable &lt;app&gt; [process-type(s)]     Enable zero-downtime deployment for all processes (or comma-separated process-type list)\nchecks:report [&lt;app&gt;] [&lt;flag&gt;]            Displays a checks report for one or more apps\nchecks:run &lt;app&gt; [process-type(s)]        Runs zero-downtime checks for all processes (or comma-separated process-type list)\nchecks:set [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt; Set or clear a logs property for an app\nchecks:skip &lt;app&gt; [process-type(s)]       Skip zero-downtime checks for all processes (or comma-separated process-type list)\n</code></pre> <p>By default, Dokku will wait <code>10</code> seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by an application, traffic will be switched to point to your new containers. Dokku will also wait a further <code>60</code> seconds after the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application.</p> <p>You may both create user-defined checks for web processes using the <code>healthchecks</code> key in the <code>app.json</code> file, as well as customize any and all parts of this experience using the checks plugin.</p> <p>Info</p> <p>Web checks are performed via <code>curl</code> on Dokku host. Some application code - such as the Django framework - checks for specific hostnames or header values, these checks will fail. To avoid this:</p> <ul> <li>Remove such checks from your code: Modify your application to remove the hostname check completely.</li> <li>Allow checks from all hostnames: Modify your application to accept a dynamically provided hostname.</li> <li>Specify the domain within the check: See below for further documentation.</li> </ul>"},{"location":"deployment/zero-downtime-deploys/#configuring-checks-settings","title":"Configuring checks settings","text":""},{"location":"deployment/zero-downtime-deploys/#wait-to-retire","title":"wait-to-retire","text":"<p>After a successful deploy, the grace period given to old containers before they are stopped/terminated is determined by the value of <code>wait-to-retire</code>. This is useful for ensuring completion of long-running HTTP connections.</p> <pre><code>dokku checks:set node-js-app wait-to-retire 30\n</code></pre> <p>Defaults to <code>60</code>.</p>"},{"location":"deployment/zero-downtime-deploys/#configuring-check-settings-using-the-config-plugin","title":"Configuring check settings using the <code>config</code> plugin","text":"<p>There are certain settings that can be configured via environment variables:</p> <ul> <li><code>DOKKU_DEFAULT_CHECKS_WAIT</code>: (default: <code>10</code>) If no user-defined checks are specified - or if the process being checked is not a <code>web</code> process - this is the period of time Dokku will wait before checking that a container is still running.</li> <li><code>DOKKU_DOCKER_STOP_TIMEOUT</code>: (default: <code>10</code>) Configurable grace period given to the <code>docker stop</code> command. If a container has not stopped by this time, a <code>kill -9</code> signal or equivalent is sent in order to force-terminate the container. Both the <code>ps:stop</code> and <code>apps:destroy</code> commands also respect this value. If not specified, the Docker defaults for the <code>docker stop</code> command will be used.</li> </ul> <p>The following settings may also be specified in the <code>app.json</code> file, though are available as environment variables in order to ease application reuse.</p> <ul> <li><code>DOKKU_CHECKS_WAIT</code>: (default: <code>5</code>) Wait this many seconds for the container to start before running checks.</li> <li><code>DOKKU_CHECKS_TIMEOUT</code>: (default: <code>30</code>) Wait this many seconds for each response before marking it as a failure.</li> <li><code>DOKKU_CHECKS_ATTEMPTS</code>: (default: <code>5</code>) Number of retries for to run for a specific check before marking it as a failure</li> </ul>"},{"location":"deployment/zero-downtime-deploys/#skipping-and-disabling-checks","title":"Skipping and Disabling Checks","text":"<p>Info</p> <p>Note that <code>checks:disable</code> will now (as of 0.6.0) cause downtime for that process-type during deployments. Previously, it acted as <code>checks:skip</code> currently does.</p> <p>You can choose to skip checks completely on a per-application/per-process basis. Skipping checks will avoid the default 10 second waiting period entirely, as well as any other user-defined checks.</p> ShellOutput <pre><code># process type specification is optional\ndokku checks:skip node-js-app worker,web\n</code></pre> <pre><code>-----&gt; Skipping zero downtime for app's (node-js-app) proctypes (worker,web)\n-----&gt; Unsetting node-js-app\n-----&gt; Unsetting DOKKU_CHECKS_DISABLED\n-----&gt; Setting config vars\n       DOKKU_CHECKS_SKIPPED: worker,web\n</code></pre> <p>Zero downtime checks can also be disabled completely. This will stop old containers before new ones start, which may result in broken connections and downtime if your application fails to boot properly.</p> ShellOutput <pre><code>dokku checks:disable node-js-app worker\n</code></pre> <pre><code>-----&gt; Disabling zero downtime for app's (node-js-app) proctypes (worker)\n-----&gt; Setting config vars\n       DOKKU_CHECKS_DISABLED: worker\n-----&gt; Setting config vars\n       DOKKU_CHECKS_SKIPPED: web\n</code></pre>"},{"location":"deployment/zero-downtime-deploys/#displaying-checks-reports-for-an-app","title":"Displaying checks reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's checks status using the <code>checks:report</code> command:</p> ShellOutput <pre><code>dokku checks:report\n</code></pre> <pre><code>=====&gt; node-js-app checks information\n       Checks disabled list: none\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n=====&gt; python-app checks information\n       Checks disabled list: none\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n=====&gt; ruby-app checks information\n       Checks disabled list: _all_\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku checks:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app checks information\n       Checks disabled list: none\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku checks:report node-js-app --checks-disabled-list\n</code></pre>"},{"location":"deployment/zero-downtime-deploys/#customizing-checks","title":"Customizing checks","text":"<p>New</p> <p>Introduced in 0.31.0</p> <p>If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use Dokku's <code>checks</code> functionality to more precisely check whether an application can serve traffic or not.</p> <p>Healthchecks are run against all process from your application's <code>Procfile</code>. When no healthcheck is defined, Dokku will fallback to a process uptime check.</p> <p>One or more healthchecks can be defined in the <code>app.json</code> file - see the deployment task documentation for more information on how this is extracted - under the <code>healthchecks.web</code> path:</p> <pre><code>{\n  \"healthchecks\": {\n    \"web\": [\n        {\n            \"type\":        \"startup\",\n            \"name\":        \"web check\",\n            \"description\": \"Checking if the app responds to the /health/ready endpoint\",\n            \"path\":        \"/health/ready\",\n            \"attempts\": 3\n        }\n    ]\n  }\n}\n</code></pre> <p>A healthcheck entry takes the following properties:</p> <ul> <li><code>attempts</code>: (default: <code>3</code>) Number of retry attempts to perform on failure.</li> <li><code>command</code>: (default <code>''</code> - empty string) Command to execute within container.</li> <li><code>content</code>: (default: <code>''</code> - empty string) Content to search in http path check output.</li> <li><code>initialDelay</code>: (default: 0, unit: seconds) Number of seconds to wait after a container has started before triggering the healthcheck.</li> <li><code>name</code>: (default: autogenerated) The name of the healthcheck. If unspecified, it will be autogenerated from the rest of the healthcheck information.</li> <li><code>path</code>: (default: <code>/</code> - for http checks): An http path to check.</li> <li><code>timeout</code>: (default: <code>5</code> seconds): Number of seconds to wait before timing out a healthcheck.</li> <li><code>type</code>: (default: <code>\"\"</code> - none): Type of the healthcheck. Options: liveness, readiness, startup.</li> <li><code>uptime</code>: (default: <code>\"\"</code> - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries.</li> <li><code>wait</code>: (default: <code>5</code> seconds): Number of seconds to wait between healthcheck attempts.</li> </ul> <p>Warning</p> <p>Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported.</p> <p>See the docker-container-healthchecker documentation for more details on how healthchecks are interpreted.</p>"},{"location":"deployment/zero-downtime-deploys/#manually-invoking-checks","title":"Manually invoking checks","text":"<p>Checks can also be manually invoked via the <code>checks:run</code> command. This can be used to check the status of an application via cron to provide integration with external healthchecking software.</p> <p>Checks are run against a specific application:</p> ShellOutput <pre><code>dokku checks:run APP\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\n-----&gt; Running checks for app (APP.web.1)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n-----&gt; Running checks for app (APP.web.2)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n-----&gt; Running checks for app (APP.worker.1)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n</code></pre> <p>Checks can be scoped to a particular process type:</p> ShellOutput <pre><code>dokku checks:run node-js-app worker\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\n-----&gt; Running checks for app (APP.worker.1)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n</code></pre> <p>An app process ID may also be specified:</p> ShellOutput <pre><code>dokku checks:run node-js-app web.2\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\n-----&gt; Running checks for app (APP.web.2)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n</code></pre> <p>Non-existent process types will result in an error:</p> ShellOutput <pre><code>dokku checks:run node-js-app non-existent\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\nInvalid process type specified (APP.non-existent)\n</code></pre> <p>Non-existent process IDs will also result in an error</p> ShellOutput <pre><code>dokku checks:run node-js-app web.3\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\nInvalid container id specified (APP.web.3)\n</code></pre>"},{"location":"deployment/builders/builder-management/","title":"Builder Management","text":"<p>New</p> <p>Introduced in 0.24.0</p> <pre><code>builder:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder report for one or more apps\nbuilder:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder property for an app\n</code></pre> <p>Builders are a way of customizing how an app is built from a source, allowing users flexibility in how artifacts are created for later scheduling.</p>"},{"location":"deployment/builders/builder-management/#usage","title":"Usage","text":""},{"location":"deployment/builders/builder-management/#builder-selection","title":"Builder selection","text":"<p>Dokku supports the following built-in builders:</p> <ul> <li><code>builder-dockerfile</code>: Builds apps using a <code>Dockerfile</code> via <code>docker build</code>. See the dockerfile builder documentation for more information on how this builder functions.</li> <li><code>builder-herokuish</code>: Builds apps with Heroku's v2a Buildpack specification via <code>gliderlabs/herokuish</code>. See the herokuish builder documentation for more information on how this builder functions.</li> <li><code>builder-lambda</code>: Builds AWS Lambda functions in an environment simulating AWS Lambda runtimes via lambda-builder. See the lambda builder documentation for more information on how this builder functions.</li> <li><code>builder-null</code>: Does nothing during the build phase. See the null builder documentation for more information on how this builder functions.</li> <li><code>builder-pack</code>: Builds apps with Cloud Native Buildpacks via the <code>pack-cli</code>  tool. See the cloud native buildpacks builder documentation for more information on how this builder functions.</li> </ul> <p>Builders run a detection script against a source code repository, and the first detected builder will be used to build the app artifact. The exception to this is when a <code>Dockerfile</code> is detected and the app is also able to use either <code>herokuish</code> or <code>pack-cli</code> for building, in which case one of the latter will be chosen.</p>"},{"location":"deployment/builders/builder-management/#overriding-the-auto-selected-builder","title":"Overriding the auto-selected builder","text":"<p>If desired, the builder can be specified via the <code>builder:set</code> command by speifying a value for <code>selected</code>. The selected builder will always be used.</p> <pre><code>dokku builder:set node-js-app selected dockerfile\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder:set node-js-app selected\n</code></pre> <p>The <code>selected</code> property can also be set globally. The global default is an empty string, and auto-detection will be performed when no value is set per-app or globally.</p> <pre><code>dokku builder:set --global selected herokuish\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder:set --global selected\n</code></pre>"},{"location":"deployment/builders/builder-management/#changing-the-build-directory","title":"Changing the build directory","text":"<p>Warning</p> <p>Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the <code>git.keep-git-dir</code> property.</p> <p>When deploying a monorepo, it may be desirable to specify the specific build directory to use for a given app. This can be done via the <code>builder:set</code> command. If a value is specified and that directory does not exist within the repository, the build will fail.</p> <pre><code>dokku builder:set node-js-app build-dir app2\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder:set node-js-app build-dir\n</code></pre> <p>The <code>build-dir</code> property can also be set globally. The global default is empty string, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder:set --global build-dir app2\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder:set --global build-dir\n</code></pre>"},{"location":"deployment/builders/builder-management/#displaying-builder-reports-for-an-app","title":"Displaying builder reports for an app","text":"<p>You can get a report about the app's builder status using the <code>builder:report</code> command:</p> ShellOutput <pre><code>dokku builder:report\n</code></pre> <pre><code>=====&gt; node-js-app builder information\n       Builder build dir:          custom\n       Builder computed build dir: custom\n       Builder computed selected:  herokuish\n       Builder global build dir:\n       Builder global selected: herokuish\n       Builder selected: herokuish\n=====&gt; python-sample builder information\n       Builder build dir:\n       Builder computed build dir:\n       Builder computed selected: dockerfile\n       Builder global build dir:\n       Builder global selected: herokuish\n       Builder selected: dockerfile\n=====&gt; ruby-sample builder information\n       Builder build dir:\n       Builder computed build dir:\n       Builder computed selected: herokuish\n       Builder global build dir:\n       Builder global selected: herokuish\n       Builder selected:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder information\n       Builder selected: herokuish\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku builder:report node-js-app --builder-selected\n</code></pre>"},{"location":"deployment/builders/builder-management/#custom-builders","title":"Custom builders","text":"<p>To create a custom builder, the following triggers must be implemented:</p> <ul> <li><code>builder-build</code>:<ul> <li>arguments: <code>BUILDER_TYPE</code> <code>APP</code> <code>SOURCECODE_WORK_DIR</code></li> <li>description: Creates a docker image named with the output of <code>common#get_app_image_name $APP</code>.</li> </ul> </li> <li><code>builder-detect</code>:<ul> <li>arguments: <code>APP</code> <code>SOURCECODE_WORK_DIR</code></li> <li>description: Outputs the name of the builder (without the <code>builder-</code> prefix) to use to build the app.</li> </ul> </li> <li><code>builder-release</code>:<ul> <li>arguments: <code>BUILDER_TYPE</code> <code>APP</code> <code>IMAGE_AG</code></li> <li>description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately.</li> </ul> </li> </ul> <p>Custom plugins names must have the prefix <code>builder-</code> or builder overriding via <code>builder:set</code> may not function as expected.</p> <p>Builders can use any tools available on the system to build the docker image, and may even be used to schedule building off-server. The only current requirement is that the image must exist on the server at the end of the <code>builder-build</code> command, though this requirement may be relaxed in a future release.</p> <p>For a simple example of how to implement this trigger, see <code>builder-pack</code>, which utilizes a cli tool - <code>pack-cli</code> - to generate an OCI image that is compatible with Docker and can be scheduled by the official scheduling plugins.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/","title":"Cloud Native Buildpacks","text":"<p>New</p> <p>Introduced in 0.22.0</p> <pre><code>builder-pack:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-pack report for one or more apps\nbuilder-pack:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-pack property for an app\n</code></pre> <pre><code>buildpacks:set-property [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt;  # Set or clear a buildpacks property for an app\n</code></pre> <p>Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the herokuish buildpacks documentation for more information on how to clear buildpack build cache for an application.</p> <p>Warning</p> <p>This functionality uses the <code>pack</code> cli from the Cloud Native Buildpacks project to build apps. As the integration is experimental in Dokku, it is likely to change over time.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/#usage","title":"Usage","text":""},{"location":"deployment/builders/cloud-native-buildpacks/#requirements","title":"Requirements","text":"<p>The <code>pack</code> cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on this page.</p> <p>Builds will proceed with the <code>pack</code> cli for the app from then on.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/#caveats","title":"Caveats","text":"<p>As this functionality is highly experimental, there are a number of caveats. Please note that not all issuesare listed below.</p> <ul> <li>Specifying specific buildpacks is not currently possible.<ul> <li>A future release will add support for specifying buildpacks via the <code>buildpacks</code> plugin.</li> </ul> </li> <li>There is currently no way to specify extra arguments for <code>pack</code> cli invocations.<ul> <li>A future release will add support for injecting extra arguments during the build process.</li> </ul> </li> <li>The default process type is <code>web</code>.</li> <li>Build cache is stored in Docker volumes instead of on disk. As such, <code>repo:purge-cache</code> currently has no effect.<ul> <li>A future version will add integration with the <code>repo</code> plugin.</li> </ul> </li> <li><code>pack</code> is not currently included with Dokku, nor is it added as a package dependency.<ul> <li>A future version will include it as a package dependency.</li> </ul> </li> </ul>"},{"location":"deployment/builders/cloud-native-buildpacks/#detection","title":"Detection","text":"<p>This builder will be auto-detected in either the following cases:</p> <ul> <li> <p>The <code>DOKKU_CNB_EXPERIMENTAL</code> app environment variable is set to <code>1</code>.</p> <pre><code>dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1\n</code></pre> </li> <li> <p>A <code>project.toml</code> file exists in the root of the app repository.</p> <ul> <li>This file is consumed by <code>pack-cli</code> and used to describe how the app is built.</li> </ul> </li> </ul> <p>The builder can also be specified via the <code>builder:set</code> command:</p> <pre><code>dokku builder:set node-js-app selected pack\n</code></pre> <p>Info</p> <p>Dokku will only select the <code>dockerfile</code> builder if both the <code>herokuish</code> and <code>pack</code> builders are not detected and a Dockerfile exists. See the dockerfile builder documentation for more information on how that builder functions.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/#changing-the-projecttoml-location","title":"Changing the <code>project.toml</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>project.toml</code> file to use for a given app. This can be done via the <code>builder-pack:set</code> command. If a value other than <code>project.toml</code> is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no <code>project.toml</code>.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>project.toml</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>project.toml</code> extracted directly from the source code. Both cases will respect the configured <code>projecttoml-path</code> property value.</p> <pre><code>dokku builder-pack:set node-js-app projecttoml-path .dokku/project.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-pack:set node-js-app projecttoml-path\n</code></pre> <p>The <code>projecttoml-path</code> property can also be set globally. The global default is <code>project.toml</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-pack:set --global projecttoml-path project2.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-pack:set --global projecttoml-path\n</code></pre>"},{"location":"deployment/builders/cloud-native-buildpacks/#displaying-builder-pack-reports-for-an-app","title":"Displaying builder-pack reports for an app","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>You can get a report about the app's storage status using the <code>builder-pack:report</code> command:</p> ShellOutput <pre><code>dokku builder-pack:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-pack information\n       Builder pack computed projecttoml path: project2.toml\n       Builder pack global projecttoml path:   project.toml\n       Builder pack projecttoml path:          project2.toml\n=====&gt; python-sample builder-pack information\n       Builder pack computed projecttoml path: project.toml\n       Builder pack global projecttoml path:   project.toml\n       Builder pack projecttoml path:\n=====&gt; ruby-sample builder-pack information\n       Builder pack computed projecttoml path: project.toml\n       Builder pack global projecttoml path:   project.json\n       Builder pack projecttoml path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-pack:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-pack information\n       Builder pack computed projecttoml path: project2.toml\n       Builder pack global projecttoml path:   project.toml\n       Builder pack projecttoml path:          project2.toml\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-pack:report node-js-app --builder-pack-projecttoml-path\n</code></pre> <pre><code>project2.toml\n</code></pre>"},{"location":"deployment/builders/cloud-native-buildpacks/#customizing-the-buildpack-stack-builder","title":"Customizing the Buildpack stack builder","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>The default stack builder in use by CNB buildpacks in Dokku is based on <code>heroku/builder:22</code>. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the <code>buildpacks:set-property</code> command.</p> <pre><code>dokku buildpacks:set-property node-js-app stack paketobuildpacks/build:base-cnb\n</code></pre> <p>The specified stack builder can also be unset by omitting the name of the stack builder when calling <code>buildpacks:set-property</code>.</p> <pre><code>dokku buildpacks:set-property node-js-app stack\n</code></pre> <p>A change in the stack builder value will execute the <code>post-stack-set</code> trigger.</p> <p>Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set <code>DOKKU_CNB_BUILDER</code> environment variable (<code>heroku/builder:22</code> by default).</p> <pre><code># set globally\ndokku buildpacks:set-property --global stack paketobuildpacks/build:base-cnb\n\n# unset globally\ndokku buildpacks:set-property --global stack\n</code></pre>"},{"location":"deployment/builders/cloud-native-buildpacks/#specifying-commands-via-procfile","title":"Specifying commands via Procfile","text":"<p>See the Procfile documentation for more information on how to specify different processes for your app.</p>"},{"location":"deployment/builders/dockerfiles/","title":"Dockerfile Deployment","text":"<p>New</p> <p>Introduced in 0.3.15</p> <pre><code>builder-dockerfile:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-dockerfile report for one or more apps\nbuilder-dockerfile:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-dockerfile property for an app\n</code></pre> <p>While Dokku normally defaults to using Heroku buildpacks for deployment, you can also use Docker's native <code>Dockerfile</code> system to define a container.</p> <p>Info</p> <p>Dockerfile support is considered a power user feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.</p>"},{"location":"deployment/builders/dockerfiles/#usage","title":"Usage","text":""},{"location":"deployment/builders/dockerfiles/#detection","title":"Detection","text":"<p>This builder will be auto-detected in the following case:</p> <ul> <li>A <code>Dockerfile</code> exists in the root of the app repository.</li> </ul> <p>Dokku will only select the <code>dockerfile</code> builder if both the <code>herokuish</code> and <code>pack</code> builders are not detected and a Dockerfile exists. For more information on how those are detected, see the following links:</p> <ul> <li>Cloud Native Buildpacks documentation</li> <li>Herokuish documentation</li> </ul>"},{"location":"deployment/builders/dockerfiles/#switching-from-buildpack-deployments","title":"Switching from buildpack deployments","text":"<p>If an application was previously deployed via buildpacks and ports were customized, the following commands should be run prior to a deploy to ensure the Dockerfile ports are respected:</p> <pre><code>dokku ports:clear node-js-app\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#changing-the-dockerfile-location","title":"Changing the <code>Dockerfile</code> location","text":"<p>Info</p> <p>The previous method to perform this - via <code>docker-options:add</code> - should be removed in favor of the <code>builder-dockerfile:set</code> command outlined here.</p> <p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>Dockerfile</code> file to use for a given app. This can be done via the <code>builder-dockerfile:set</code> command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.</p> <p>For git push, <code>git:from-archive</code>, and <code>git:sync</code> workflows, the <code>Dockerfile</code> is extracted directly from the source code, respecting the configured <code>dockerfile-path</code> property value.</p> <pre><code>dokku builder-dockerfile:set node-js-app dockerfile-path Dockerfile2\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-dockerfile:set node-js-app dockerfile-path\n</code></pre> <p>The <code>dockerfile-path</code> property can also be set globally. The global default is <code>Dockerfile</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-dockerfile:set --global dockerfile-path Dockerfile2\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-dockerfile:set --global dockerfile-path\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#displaying-builder-dockerfile-reports-for-an-app","title":"Displaying builder-dockerfile reports for an app","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>You can get a report about the app's storage status using the <code>builder-dockerfile:report</code> command:</p> ShellOutput <pre><code>dokku builder-dockerfile:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile2\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:          Dockerfile2\n=====&gt; python-sample builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:\n=====&gt; ruby-sample builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-dockerfile:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile2\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:          Dockerfile2\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-dockerfile:report node-js-app --builder-dockerfile-dockerfile-path\n</code></pre> <pre><code>Dockerfile2\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#build-time-configuration-variables","title":"Build-time configuration variables","text":"<p>For security reasons - and as per Docker recommendations - Dockerfile-based deploys have variables available only during runtime.</p> <p>For users that require customization in the <code>build</code> phase, you may use build arguments via the docker-options plugin. All environment variables set by the <code>config</code> plugin are automatically exported during a docker build, and thus <code>--build-arg</code> only requires setting a key without a value.</p> <pre><code>dokku docker-options:add node-js-app build '--build-arg NODE_ENV'\n</code></pre> <p>Once set, the Dockerfile usage would be as follows:</p> <pre><code>FROM ubuntu:20.04\n\n# set the argument default\nARG NODE_ENV=production\n\n# use the argument\nRUN echo $NODE_ENV\n</code></pre> <p>You may also set the argument as an environment variable</p> <pre><code>FROM ubuntu:20.04\n\n# set the argument default\nARG NODE_ENV=production\n\n# assign it to an environment variable\n# we can wrap the variable in brackets\nENV NODE_ENV ${NODE_ENV}\n\n# or omit them completely\n\n# use the argument\nRUN echo $NODE_ENV\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#building-images-with-docker-buildkit","title":"Building images with Docker BuildKit","text":"<p>If your Dockerfile is using Docker Engine's BuildKit (not to be confused with buildpacks), then the <code>DOCKER_BUILDKIT=1</code> environment variable needs to be set (unless you're using Docker Engine v24 or higher, which uses BuildKit by default). Additionally, complete build log output can be forced via <code>BUILDKIT_PROGRESS=plain</code>. Both of these environment variables can be set as follows:</p> <pre><code>echo \"export DOCKER_BUILDKIT=1\" | sudo tee -a /etc/default/dokku\necho \"export BUILDKIT_PROGRESS=plain\" | sudo tee -a /etc/default/dokku\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#buildkit-directory-caching","title":"BuildKit directory caching","text":"<p>BuildKit implements the <code>RUN --mount</code> option, enabling mount directory caches for <code>RUN</code> directives. The following is an example that mounts debian packaging related directories, which can speed up fetching of remote package data.</p> <pre><code>FROM debian:latest\nRUN --mount=target=/var/lib/apt/lists,type=cache \\\n    --mount=target=/var/cache/apt,type=cache \\\n    apt-get update \\\n &amp;&amp; DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \\\n      git\n</code></pre> <p>Mount cache targets may vary depending on the tool in use, and users are encouraged to investigate the directories that apply for their language and framework.</p> <p>You would adjust the cache directory for whatever application cache you have, e.g. <code>/root/.pnpm-store/v3</code> for pnpm, <code>$HOME/.m2</code> for maven, or <code>/root/.cache</code> for golang.</p>"},{"location":"deployment/builders/dockerfiles/#customizing-the-run-command","title":"Customizing the run command","text":"<p>By default no arguments are passed to <code>docker run</code> when deploying the container and the <code>CMD</code> or <code>ENTRYPOINT</code> defined in the <code>Dockerfile</code> are executed. You can take advantage of docker ability of overriding the <code>CMD</code> or passing parameters to your <code>ENTRYPOINT</code> setting <code>$DOKKU_DOCKERFILE_START_CMD</code>. Let's say for example you are deploying a base Node.js image, with the following <code>ENTRYPOINT</code>:</p> <pre><code>ENTRYPOINT [\"node\"]\n</code></pre> <p>You can do:</p> <pre><code>dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD=\"--harmony server.js\"\n</code></pre> <p>To tell Docker what to run.</p> <p>Setting <code>$DOKKU_DOCKERFILE_CACHE_BUILD</code> to <code>true</code> or <code>false</code> will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any <code>docker build</code> option to <code>docker</code>, by setting <code>$DOKKU_DOCKER_BUILD_OPTS</code>.</p>"},{"location":"deployment/builders/dockerfiles/#procfiles-and-multiple-processes","title":"Procfiles and multiple processes","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>See the Procfile documentation for more information on how to specify different processes for your app.</p>"},{"location":"deployment/builders/dockerfiles/#exposed-ports","title":"Exposed ports","text":"<p>See the port management documentation for more information on how Dokku exposes ports for applications and how you can configure these for your app.</p>"},{"location":"deployment/builders/herokuish-buildpacks/","title":"Herokuish Buildpacks","text":"<p>New</p> <p>Subcommands introduced in 0.15.0</p> <pre><code>buildpacks:add [--index 1] &lt;app&gt; &lt;buildpack&gt;            # Add new app buildpack while inserting into list of buildpacks if necessary\nbuildpacks:clear &lt;app&gt;                                  # Clear all buildpacks set on the app\nbuildpacks:list &lt;app&gt;                                   # List all buildpacks for an app\nbuildpacks:remove &lt;app&gt; &lt;buildpack&gt;                     # Remove a buildpack set on the app\nbuildpacks:report [&lt;app&gt;] [&lt;flag&gt;]                      # Displays a buildpack report for one or more apps\nbuildpacks:set [--index 1] &lt;app&gt; &lt;buildpack&gt;            # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified\nbuildpacks:set-property [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt;  # Set or clear a buildpacks property for an app\n</code></pre> <pre><code>builder-herokuish:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-herokuish report for one or more apps\nbuilder-herokuish:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-herokuish property for an app\n</code></pre> <p>Warning</p> <p>If using the <code>buildpacks</code> plugin, be sure to unset any <code>BUILDPACK_URL</code> and remove any such entries from a committed <code>.env</code> file. A specified <code>BUILDPACK_URL</code> will always override a <code>.buildpacks</code> file or the buildpacks plugin.</p> <p>Dokku normally defaults to using Heroku buildpacks for deployment, though this may be overridden by committing a valid <code>Dockerfile</code> to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic <code>Dockerfile</code> deployment detection, you may do one of the following:</p> <ul> <li>Set a <code>BUILDPACK_URL</code> environment variable<ul> <li>This can be done via <code>dokku config:set</code> or via a committed <code>.env</code> file in the root of the repository. See the environment variable documentation for more details.</li> </ul> </li> <li>Create a <code>.buildpacks</code> file in the root of your repository.<ul> <li>This can be via a committed <code>.buildpacks</code> file or managed via the <code>buildpacks</code> plugin commands.</li> </ul> </li> </ul> <p>This page will cover usage of the <code>buildpacks</code> plugin.</p>"},{"location":"deployment/builders/herokuish-buildpacks/#usage","title":"Usage","text":""},{"location":"deployment/builders/herokuish-buildpacks/#detection","title":"Detection","text":"<p>This builder will be auto-detected in either the following cases:</p> <ul> <li>The <code>BUILDPACK_URL</code> app environment variable is set.<ul> <li>This can be done via <code>dokku config:set</code> or via a committed <code>.env</code> file in the root of the repository. See the environment variable documentation for more details.</li> </ul> </li> <li>A <code>.buildpacks</code> file exists in the root of the app repository.<ul> <li>This can be via a committed <code>.buildpacks</code> file or managed via the <code>buildpacks</code> plugin commands.</li> </ul> </li> </ul> <p>The builder can also be specified via the <code>builder:set</code> command:</p> <pre><code>dokku builder:set node-js-app selected herokuish\n</code></pre> <p>Info</p> <p>Dokku will only select the <code>dockerfile</code> builder if both the <code>herokuish</code> and <code>pack</code> builders are not detected and a Dockerfile exists. See the dockerfile builder documentation for more information on how that builder functions.</p>"},{"location":"deployment/builders/herokuish-buildpacks/#listing-buildpacks-in-use","title":"Listing Buildpacks in Use","text":"<p>The <code>buildpacks:list</code> command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.</p> ShellOutputShellOutput <pre><code># running for an app with no buildpacks specified\ndokku buildpacks:list node-js-app\n</code></pre> <pre><code>-----&gt; test buildpack urls\n</code></pre> <pre><code># running for an app with two buildpacks specified\ndokku buildpacks:list node-js-app\n</code></pre> <pre><code>-----&gt; test buildpack urls\n       https://github.com/heroku/heroku-buildpack-python.git\n       https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#adding-custom-buildpacks","title":"Adding custom buildpacks","text":"<p>Info</p> <p>Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.</p> <p>To add a custom buildpack, use the <code>buildpacks:add</code> command:</p> <pre><code>dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre> <p>When no buildpacks are currently specified, the specified buildpack will be the only one executed for detection and compilation.</p> <p>Multiple buildpacks may be specified by using the <code>buildpacks:add</code> command multiple times.</p> <pre><code>dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\ndokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre> <p>Buildpacks are executed in order, may be inserted at a specified index via the <code>--index</code> flag. This flag is specified starting at a 1-index value.</p> <pre><code># will add the golang buildpack at the second position, bumping all proceeding ones by 1 position\ndokku buildpacks:add --index 2 node-js-app https://github.com/heroku/heroku-buildpack-golang.git\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#overwriting-a-buildpack-position","title":"Overwriting a buildpack position","text":"<p>In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the <code>buildpacks:set</code> command can be used to overwrite a buildpack at a given position.</p> <pre><code>dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre> <p>By default, this will overwrite the first buildpack specified. To specify an index, the <code>--index</code> flag may be used. This flag is specified starting at a 1-index value, and defaults to <code>1</code>.</p> <pre><code># the following are equivalent commands\ndokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\ndokku buildpacks:set --index 1 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre> <p>If the index specified is larger than the number of buildpacks currently configured, the buildpack will be appended to the end of the list.</p> <pre><code>dokku buildpacks:set --index 99 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#removing-a-buildpack","title":"Removing a buildpack","text":"<p>Info</p> <p>At least one of a buildpack or index must be specified</p> <p>A single buildpack can be removed by name via the <code>buildpacks:remove</code> command.</p> <pre><code>dokku buildpacks:remove node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre> <p>Buildpacks can also be removed by index via the <code>--index</code> flag. This flag is specified starting at a 1-index value.</p> <pre><code>dokku buildpacks:remove node-js-app --index 1\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#clearing-all-buildpacks","title":"Clearing all buildpacks","text":"<p>Info</p> <p>This does not affect automatically detected buildpacks, nor does it impact any specified <code>BUILDPACK_URL</code> environment variable.</p> <p>The <code>buildpacks:clear</code> command can be used to clear all configured buildpacks for a specified app.</p> <pre><code>dokku buildpacks:clear node-js-app\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#customizing-the-buildpack-stack-builder","title":"Customizing the Buildpack stack builder","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>The default stack builder in use by Herokuish buildpacks in Dokku is based on <code>gliderlabs/herokuish:latest</code>. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the <code>buildpacks:set-property</code> command.</p> <pre><code>dokku buildpacks:set-property node-js-app stack gliderlabs/herokuish:latest\n</code></pre> <p>The specified stack builder can also be unset by omitting the name of the stack builder when calling <code>buildpacks:set-property</code>.</p> <pre><code>dokku buildpacks:set-property node-js-app stack\n</code></pre> <p>A change in the stack builder value will execute the <code>post-stack-set</code> trigger.</p> <p>Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set <code>DOKKU_IMAGE</code> environment variable (<code>gliderlabs/herokuish:latest-22</code> by default).</p> <pre><code># set globally\ndokku buildpacks:set-property --global stack gliderlabs/herokuish:latest\n\n# unset globally\ndokku buildpacks:set-property --global stack\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#allowing-herokuish-for-non-amd64-platforms","title":"Allowing herokuish for non-amd64 platforms","text":"<p>New</p> <p>Introduced in 0.29.0</p> <p>By default, the builder-herokuish plugin is not enabled for non-amd64 platforms, and attempting to use it is blocked. This is because the majority of buildpacks are not cross-platform compatible, and thus building apps will either be considerably slower - due to emulating the amd64 platform - or won't work - due to building amd64 packages on arm64 platforms.</p> <p>To force-enable herokuish on non-amd64 platforms, the <code>allowed</code> property can be set via <code>builder-herokuish:set</code>. The default value depends on the host platform architecture (<code>true</code> on amd64, <code>false</code> otherwise).</p> <pre><code>dokku builder-herokuish:set node-js-app allowed true\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-herokuish:set node-js-app allowed\n</code></pre> <p>The <code>allowed</code> property can also be set globally. The global default is platform-dependent, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-herokuish:set --global allowed true\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-herokuish:set --global allowed\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#displaying-buildpack-reports-for-an-app","title":"Displaying buildpack reports for an app","text":"<p>You can get a report about the app's buildpacks status using the <code>buildpacks:report</code> command:</p> ShellOutput <pre><code>dokku buildpacks:report\n</code></pre> <pre><code>=====&gt; node-js-app buildpacks information\n       Buildpacks computed stack:  gliderlabs/herokuish:v0.7.0-22\n       Buildpacks global stack:    gliderlabs/herokuish:latest-22\n       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git\n       Buildpacks stack:           gliderlabs/herokuish:v0.7.0-20\n=====&gt; python-sample buildpacks information\n       Buildpacks computed stack:  gliderlabs/herokuish:latest-22\n       Buildpacks global stack:    gliderlabs/herokuish:latest-22\n       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git\n       Buildpacks stack:\n=====&gt; ruby-sample buildpacks information\n       Buildpacks computed stack:  gliderlabs/herokuish:latest-22\n       Buildpacks global stack:    gliderlabs/herokuish:latest-22\n       Buildpacks list:\n       Buildpacks stack:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku buildpacks:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app buildpacks information\n       Buildpacks list:               https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku buildpacks:report node-js-app --buildpacks-list\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#displaying-builder-herokuish-reports-for-an-app","title":"Displaying builder-herokuish reports for an app","text":"<p>New</p> <p>Introduced in 0.29.0</p> <p>You can get a report about the app's storage status using the <code>builder-herokuish:report</code> command:</p> ShellOutput <pre><code>dokku builder-herokuish:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-herokuish information\n       Builder herokuish computed allowed: false\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:          false\n=====&gt; python-sample builder-herokuish information\n       Builder herokuish computed allowed: true\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:\n=====&gt; ruby-sample builder-herokuish information\n       Builder herokuish computed allowed: true\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-herokuish:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-herokuish information\n       Builder herokuish computed allowed: false\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:          false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-herokuish:report node-js-app --builder-herokuish-allowed\n</code></pre> <pre><code>false\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#errata","title":"Errata","text":""},{"location":"deployment/builders/herokuish-buildpacks/#switching-from-dockerfile-deployments","title":"Switching from Dockerfile deployments","text":"<p>If an application was previously deployed via Dockerfile, the following commands should be run before a buildpack deploy will succeed:</p> <pre><code>dokku ports:clear node-js-app\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#using-a-specific-buildpack-version","title":"Using a specific buildpack version","text":"<p>Info</p> <p>Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.</p> <p>By default, Dokku uses the gliderlabs/herokuish project, which pins all of it's vendored buildpacks. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified without a Git commit SHA like so:</p> <pre><code># using the latest nodejs buildpack\ndokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs\n</code></pre> <p>This will use the latest commit on the <code>master</code> branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form <code>REPOSITORY_URL#COMMIT_SHA</code>, where <code>COMMIT_SHA</code> is any tree-ish git object - usually a git tag.</p> <pre><code># using v87 of the nodejs buildpack\ndokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#curl-build-timeouts","title":"<code>curl</code> build timeouts","text":"<p>Certain buildpacks may time out in retrieving dependencies via <code>curl</code>. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to <code>gzip: stdin: unexpected end of file</code> after a <code>curl</code> command.</p> <p>If you see output similar this when deploying , you may need to override the <code>curl</code> timeouts to increase the length of time allotted to those tasks. You can do so via the <code>config</code> plugin:</p> <pre><code>dokku config:set --global CURL_TIMEOUT=1200\ndokku config:set --global CURL_CONNECT_TIMEOUT=180\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#clearing-buildpack-cache","title":"Clearing buildpack cache","text":"<p>See the repository management documentation for more information on how to clear buildpack build cache for an application.</p>"},{"location":"deployment/builders/herokuish-buildpacks/#specifying-commands-via-procfile","title":"Specifying commands via Procfile","text":"<p>See the Procfile documentation for more information on how to specify different processes for your app.</p>"},{"location":"deployment/builders/lambda/","title":"Lambda Builder","text":"<p>New</p> <p>Introduced in 0.28.0</p> <pre><code>builder-lambda:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-lambda report for one or more apps\nbuilder-lambda:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-lambda property for an app\n</code></pre> <p>The <code>lambda</code> builder builds AWS Lambda functions in an environment simulating AWS Lambda runtimes via lambda-builder. Apps built via this builder can run natively in Dokku and may also have their artifacts scheduled to Lambda via an appropriate scheduler.</p>"},{"location":"deployment/builders/lambda/#usage","title":"Usage","text":""},{"location":"deployment/builders/lambda/#detection","title":"Detection","text":"<p>This builder will be auto-detected in the following case:</p> <ul> <li>A <code>lambda.yml</code> exists in the root of the app repository.</li> </ul> <p>The builder may also be selected via the <code>builder:set</code> command</p> <pre><code>dokku builder:set node-js-app selected lambda\n</code></pre>"},{"location":"deployment/builders/lambda/#supported-languages","title":"Supported languages","text":"<p>The <code>lambda</code> builder plugin supports the following AWS runtime languages on Amazon Linux 2:</p> <ul> <li>dotnet</li> <li>go (builder is based on AL1)</li> <li>nodejs</li> <li>python</li> <li>ruby</li> </ul> <p>See the lambda-builder documentation for more information on how specific languages are detected.</p>"},{"location":"deployment/builders/lambda/#customizing-the-build-environment","title":"Customizing the build environment","text":"<p>The <code>lambda</code> builder plugin delegates all build logic to lambda-builder, including language detection and build/runtime environment specification. The lambda-builder tool supports a <code>lambda.yml</code> file format for customizing how apps are built. Please see the readme for lambda-builder for more information on different options.</p>"},{"location":"deployment/builders/lambda/#changing-the-lambdayml-location","title":"Changing the <code>lambda.yml</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>lambda.yml</code> file to use for a given app. This can be done via the <code>builder-lambda:set</code> command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>lambda.yml</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>lambda.yml</code> extracted directly from the source code. Both cases will respect the configured <code>lambdayml-path</code> property value.</p> <pre><code>dokku builder-lambda:set node-js-app lambdayml-path .dokku/lambda.yml\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-lambda:set node-js-app lambdayml-path\n</code></pre> <p>The <code>lambdayml-path</code> property can also be set globally. The global default is <code>lambda.yml</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-lambda:set --global lambdayml-path lambda2.yml\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-lambda:set --global lambdayml-path\n</code></pre>"},{"location":"deployment/builders/lambda/#displaying-builder-lambda-reports-for-an-app","title":"Displaying builder-lambda reports for an app","text":"<p>You can get a report about the app's storage status using the <code>builder-lambda:report</code> command:</p> ShellOutput <pre><code>dokku builder-lambda:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-lambda information\n       Builder lambda computed lambdayml path: lambda2.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:          lambda2.yml\n=====&gt; python-sample builder-lambda information\n       Builder lambda computed lambdayml path: lambda.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:\n=====&gt; ruby-sample builder-lambda information\n       Builder lambda computed lambdayml path: lambda.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-lambda:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-lambda information\n       Builder lambda computed lambdayml path: lambda2.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:          lambda2.yml\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-lambda:report node-js-app --builder-lambda-lambdayml-path\n</code></pre> <pre><code>lambda2.yml\n</code></pre>"},{"location":"deployment/builders/nixpacks/","title":"Nixpacks","text":"<p>New</p> <p>Introduced in 0.32.0</p> <p>The <code>nixpacks</code> builder builds apps via Nixpacks, a buildpack alternative.</p>"},{"location":"deployment/builders/nixpacks/#usage","title":"Usage","text":""},{"location":"deployment/builders/nixpacks/#requirements","title":"Requirements","text":"<p>The <code>nixpacks</code> cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on this page.</p> <p>Builds will proceed with the <code>nixpacks</code> cli for the app from then on.</p>"},{"location":"deployment/builders/nixpacks/#detection","title":"Detection","text":"<p>This builder will be auto-detected in the following case:</p> <ul> <li>A <code>nixpacks.toml</code> exists in the root of the app repository.</li> </ul> <p>The builder may also be selected via the <code>builder:set</code> command</p> <pre><code>dokku builder:set node-js-app selected nixpacks\n</code></pre>"},{"location":"deployment/builders/nixpacks/#supported-languages","title":"Supported languages","text":"<p>See the upstream nixpacks documentation for further information on what languages and frameworks are supported.</p>"},{"location":"deployment/builders/nixpacks/#build-time-configuration-variables","title":"Build-time configuration variables","text":"<p>For security reasons - and as per Docker recommendations - nixpacks-based deploys have variables available only during runtime.</p> <p>For users that require customization in the <code>build</code> phase, you may use build arguments via the docker-options plugin. All environment variables set by the <code>config</code> plugin are automatically exported within the nixpacks build environment, and thus <code>--env</code> only requires setting a key without a value.</p> <pre><code>dokku docker-options:add node-js-app build '--env NODE_ENV'\n</code></pre> <p>Alternatively, a full value may be provided in the form of <code>--env KEY=VALUE</code>:</p> <pre><code>dokku docker-options:add node-js-app build '--env NODE_ENV=production'\n</code></pre>"},{"location":"deployment/builders/nixpacks/#changing-the-nixpackstoml-location","title":"Changing the <code>nixpacks.toml</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>nixpacks.toml</code> file to use for a given app. This can be done via the <code>builder-nixpacks:set</code> command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.</p> <pre><code>dokku builder-nixpacks:set node-js-app nixpackstoml-path nixpacks2.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-nixpacks:set node-js-app nixpackstoml-path\n</code></pre> <p>The <code>nixpackstoml-path</code> property can also be set globally. The global default is <code>nixpacks.toml</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-nixpacks:set --global nixpackstoml-path nixpacks2.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-nixpacks:set --global nixpackstoml-path\n</code></pre>"},{"location":"deployment/builders/nixpacks/#disabling-cache","title":"Disabling cache","text":"<p>Cache is enabled by default, but can be disabled by setting the <code>no-cache</code> property to <code>true</code>:</p> <pre><code>dokku builder-nixpacks:set node-js-app no-cache true\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-nixpacks:set node-js-app no-cache\n</code></pre> <p>The <code>no-cache</code> property can also be set globally. The global default is <code>false</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-nixpacks:set --global no-cache true\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-nixpacks:set --global no-cache\n</code></pre>"},{"location":"deployment/builders/nixpacks/#displaying-builder-nixpacks-reports-for-an-app","title":"Displaying builder-nixpacks reports for an app","text":"<p>You can get a report about the app's storage status using the <code>builder-nixpacks:report</code> command:</p> ShellOutput <pre><code>dokku builder-nixpacks:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks2.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:          nixpacks2.toml\n       Builder-nixpacks computed no cache:          true\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:                   true\n=====&gt; python-sample builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:\n       Builder-nixpacks computed no cache:          false\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:\n=====&gt; ruby-sample builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:\n       Builder-nixpacks computed no cache:          false\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-nixpacks:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks2.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:          nixpacks2.toml\n       Builder-nixpacks computed no cache:          true\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:                   true\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-nixpacks:report node-js-app --builder-nixpacks-no-cache\n</code></pre> <pre><code>true\n</code></pre>"},{"location":"deployment/builders/null/","title":"Null Builder","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>The <code>null</code> builder does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the network documentation for more information on the aforementioned use case.</p>"},{"location":"deployment/builders/null/#usage","title":"Usage","text":""},{"location":"deployment/builders/null/#detection","title":"Detection","text":"<p>This builder is never auto-detected. The builder must  be specified via the <code>builder:set</code> command:</p> <pre><code>dokku builder:set node-js-app selected null\n</code></pre>"},{"location":"deployment/continuous-integration/generic/","title":"Generic CI/CD Integration","text":"<p>In cases where there is no direct or documented integration available, the Dokku project provides an Official Docker Image for use in Continuous Integration/Continuous Deployment (CI/CD) systems.</p> <p>Assuming a Docker image can be run as a CI task with environment variables injected, the following CI systems will have their variables automatically detected:</p> <ul> <li>circleci</li> <li>cloudbees</li> <li>drone</li> <li>github actions</li> <li>gitlab-ci</li> <li>semaphoreci</li> <li>travisci</li> </ul>"},{"location":"deployment/continuous-integration/generic/#simple-usage","title":"Simple Usage","text":"<p>The simplest usage of the image is as follows.</p> <pre><code># where the `.env` file contains `GIT_REMOTE_URL` and `SSH_PRIVATE_KEY`\n\ndocker run --rm -v=\"$PWD:/app\" --env-file=.env dokku/ci-docker-image dokku-deploy\n</code></pre> <p>For more configuration examples and further documentation, see the ci-docker-image readme.</p>"},{"location":"deployment/continuous-integration/github-actions/","title":"GitHub Actions","text":"<p>The Dokku project has an official GitHub Action available on the GitHub Marketplace. The simplest usage example is as follows:</p> <pre><code>---\nname: 'deploy'\n\non:\n  push:\n    branches:\n      - master\n\njobs:\n  deploy:\n    runs-on: ubuntu-22.04\n    steps:\n      - name: Cloning repo\n        uses: actions/checkout@v3\n        with:\n          fetch-depth: 0\n\n      - name: Push to dokku\n        uses: dokku/github-action@master\n        with:\n          git_remote_url: 'ssh://dokku@dokku.me:22/appname'\n          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}\n</code></pre> <p>For further usage documentation and other advanced examples, see the entry on the GitHub Marketplace.</p>"},{"location":"deployment/continuous-integration/gitlab-ci/","title":"GitLab CI","text":"<p>GitLab CI can be used to automatically deploy a Dokku application via the official the dokku/ci-docker-image. The simplest example is as follows:</p> <pre><code>---\nimage: dokku/ci-docker-image\n\nstages:\n  - deploy\n\nvariables:\n  GIT_DEPTH: 0\n\ndeploy:\n  stage: deploy\n  only:\n    - master\n  variables:\n    GIT_REMOTE_URL: ssh://dokku@dokku.me:22/appname\n  script: \n    - dokku-deploy\n  after_script: \n    - dokku-unlock\n</code></pre> <p>For further usage documentation and other advanced examples, see Dokku's gitlab-ci repository.</p>"},{"location":"deployment/methods/archive/","title":"Tar and Zip Archives","text":""},{"location":"deployment/methods/archive/#initializing-an-app-repository-from-an-archive-file","title":"Initializing an app repository from an archive file","text":"<p>New</p> <p>Introduced in 0.24.0</p> <p>A Dokku app repository can be initialized or updated from the contents of an archive file via the <code>git:from-archive</code> command. This is an excellent way of tracking changes when deploying pre-built binary archives, such as java jars or go binaries. This can also be useful when deploying directly from a GitHub repository at a specific commit.</p> <pre><code>dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar\n</code></pre> <p>In the above example, Dokku will build the app as if the repository contained the extracted contents of the specified archive file.</p> <p>Triggering a build with the same archive file multiple times will result in Dokku exiting <code>0</code> early as there will be no changes detected.</p> <p>The <code>git:from-archive</code> command can optionally take a git <code>user.name</code> and <code>user.email</code> argument (in that order) to customize the author. If the arguments are left empty, they will fallback to <code>Dokku</code> and <code>automated@dokku.sh</code>, respectively.</p> <pre><code>dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar \"Camila\" \"camila@example.com\"\n</code></pre> <p>The default archive type is always set to <code>.tar</code>. To use a different archive type, specify the <code>--archive-type</code> flag. Failure to do so will result in a failure to extract the archive.</p> <pre><code>dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip \"Camila\" \"camila@example.com\"\n</code></pre> <p>Finally, if the archive url is specified as <code>--</code>, the archive will be fetched from stdin.</p> <pre><code>curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar | dokku git:from-archive node-js-app  --\n</code></pre>"},{"location":"deployment/methods/git/","title":"Git Deployment","text":"<p>New</p> <p>Subcommands introduced in 0.12.0</p> <pre><code>git:allow-host &lt;host&gt;                             # Adds a host to known_hosts\ngit:auth &lt;host&gt; [&lt;username&gt; &lt;password&gt;]           # Configures netrc authentication for a given git server\ngit:from-archive [--archive-type ARCHIVE_TYPE] &lt;app&gt; &lt;archive-url&gt; [&lt;git-username&gt; &lt;git-email&gt;] # Updates an app's git repository with a given archive file\ngit:from-image [--build-dir DIRECTORY] &lt;app&gt; &lt;docker-image&gt; [&lt;git-username&gt; &lt;git-email&gt;] # Updates an app's git repository with a given docker image\ngit:generate-deploy-key                           # Generates a deploy ssh key\ngit:load-image [--build-dir DIRECTORY] &lt;app&gt; &lt;docker-image&gt; [&lt;git-username&gt; &lt;git-email&gt;] # Updates an app's git repository with a docker image loaded from stdin\ngit:sync [--build] &lt;app&gt; &lt;repository&gt; [&lt;git-ref&gt;] # Clone or fetch an app from remote git repo\ngit:initialize &lt;app&gt;                              # Initialize a git repository for an app\ngit:public-key                                    # Outputs the dokku public deploy key\ngit:report [&lt;app&gt;] [&lt;flag&gt;]                       # Displays a git report for one or more apps\ngit:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)                     # Set or clear a git property for an app\ngit:status &lt;app&gt;                                  # Show the working tree status for an app\ngit:unlock &lt;app&gt; [--force]                        # Removes previous git clone folder for new deployment\n</code></pre> <p>Git-based deployment has been the traditional method of deploying applications in Dokku. As of v0.12.0, Dokku introduces a few ways to customize the experience of deploying via <code>git push</code>. A Git-based deployment currently supports building applications via:</p> <ul> <li>Cloud Native Buildpacks</li> <li>Herokuish Buildpack</li> <li>Dockerfiles</li> </ul>"},{"location":"deployment/methods/git/#usage","title":"Usage","text":"<p>Warning</p> <p>Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process.</p>"},{"location":"deployment/methods/git/#initializing-an-application","title":"Initializing an application","text":"<p>When an application is created via <code>git push</code>, Dokku will create the proper <code>pre-receive</code> hook in order to execute the build pipeline. In certain cases - such as when fronting deploys with the <code>git-http-backend</code> - this may not be correctly created. As an alternative, the <code>git:initialize</code> command can be used to trigger this creation:</p> <pre><code># on the Dokku host\n\n# overrides any existing pre-receive hook\ndokku git:initialize node-js-app\n</code></pre> <p>In order for the above command to succeed, the application must already exist.</p> <p>Warning</p> <p>If the <code>pre-receive</code> hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.</p>"},{"location":"deployment/methods/git/#changing-the-deploy-branch","title":"Changing the deploy branch","text":"<p>By default, Dokku will deploy code pushed to the <code>master</code> branch. In order to quickly deploy a different local branch, the following Git command can be used:</p> <pre><code># on the local machine\n\n# where `SOME_BRANCH_NAME` is the name of the branch\ngit push dokku SOME_BRANCH_NAME:master\n</code></pre> <p>In <code>0.12.0</code>, the correct way to change the deploy branch is to use the <code>git:set</code> Dokku command.</p> <pre><code># on the Dokku host\n\n# override for all applications\ndokku git:set --global deploy-branch SOME_BRANCH_NAME\n\n# override for a specific app\n# where `SOME_BRANCH_NAME` is the name of the branch\ndokku git:set node-js-app deploy-branch SOME_BRANCH_NAME\n</code></pre> <p>As of 0.22.1, Dokku will also respect the first pushed branch as the primary branch, and automatically set the <code>deploy-branch</code> value at that time.</p> <p>Pushing multiple branches can also be supported by creating a receive-branch plugin trigger in a custom plugin.</p>"},{"location":"deployment/methods/git/#configuring-the-git_rev-environment-variable","title":"Configuring the <code>GIT_REV</code> environment variable","text":"<p>New</p> <p>Introduced in 0.12.0</p> <p>Application deployments will include a special <code>GIT_REV</code> environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same.</p> <p>To configure the name of the <code>GIT_REV</code> environment variable, run the <code>git:set</code> command as follows:</p> <pre><code># on the Dokku host\n\n# override for a specific app\ndokku git:set node-js-app rev-env-var DOKKU_GIT_REV\n</code></pre> <p>This behavior can be disabled entirely on a per-app basis by setting the <code>rev-env-var</code> value to an empty string:</p> <pre><code># on the Dokku host\n\n# override for a specific app\ndokku git:set node-js-app rev-env-var \"\"\n</code></pre>"},{"location":"deployment/methods/git/#keeping-the-git-directory","title":"Keeping the <code>.git</code> directory","text":"<p>By default, Dokku will remove the contents of the <code>.git</code> before triggering a build for a given app. This is generally a safe default as shipping the entire source code history of your app in the deployed image artifact is unnecessary as it increases bloat and potentially can leak information if there are any security issues with your app code.</p> <p>To enable the <code>.git</code> directory, run the <code>git:set</code> command as follows:</p> <pre><code># on the Dokku host\n\n# keep the .git directory during builds\ndokku git:set node-js-app keep-git-dir true\n</code></pre> <p>The default behavior is to delete this directory and it's contents. To revert to the default behavior, the <code>keep-git-dir</code> value can be set to either an empty string or <code>false</code>.</p> <pre><code># on the Dokku host\n\n# delete the .git directory during builds (default)\ndokku git:set node-js-app keep-git-dir false\n\n# delete the .git directory during builds (default)\ndokku git:set node-js-app keep-git-dir \"\"\n</code></pre> <p>Please keep in mind that setting <code>keep-git-dir</code> to <code>true</code> may result in unstaged changes shown within the built container due to the build process generating application changes within the built app directory.</p>"},{"location":"deployment/methods/git/#initializing-an-app-repository-from-a-remote-repository","title":"Initializing an app repository from a remote repository","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>A Dokku app repository can be initialized or updated from a remote git repository via the <code>git:sync</code> command. This command will either clone or fetch updates from a remote repository and has undefined behavior if the history cannot be fast-fowarded to the referenced repository reference. Any repository that can be cloned by the <code>dokku</code> user can be specified.</p> <p>Info</p> <p>The application must exist before the repository can be initialized</p> <pre><code>dokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git\n</code></pre> <p>The <code>git:sync</code> command optionally takes an optional third parameter containing a git reference, which may be a branch, tag, or specific commit.</p> <pre><code># specify a branch\ndokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git main\n\n# specify a tag\ndokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git 1\n\n# specify a commit\ndokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git 97e6c72491c7531507bfc5413903e0e00e31e1b0\n</code></pre> <p>By default, this command does not trigger an application build. To do so during a <code>git:sync</code>, specify the <code>--build</code> flag.</p> <pre><code>dokku git:sync --build node-js-app https://github.com/heroku/node-js-getting-started.git\n</code></pre>"},{"location":"deployment/methods/git/#initializing-from-private-repositories","title":"Initializing from private repositories","text":"<p>New</p> <p>Introduced in 0.24.0</p> <p>Initializing from a private repository requires one of the following:</p> <ul> <li>A Public SSH Key (<code>id_rsa.pub</code> file) configured on the remote server, with the associated private key (<code>id_rsa</code>) in the Dokku server's <code>/home/dokku/.ssh/</code> directory.</li> <li>A configured <code>.netrc</code> entry.</li> </ul> <p>Dokku provides the <code>git:auth</code> command which can be used to configure a <code>netrc</code> entry for the remote server. This command can be used to add or remove configuration for any remote server.</p> <pre><code># add credentials for github.com\ndokku git:auth github.com username personal-access-token\n\n# remove credentials for github.com\ndokku git:auth github.com\n</code></pre> <p>For syncing to a private repository stored on a remote Git product such as GitHub or GitLab, Dokku's recommendation is to use a personal access token on a bot user where possible. Please see your service's documentation for information regarding the recommended best practices.</p>"},{"location":"deployment/methods/git/#allowing-remote-repository-hosts","title":"Allowing remote repository hosts","text":"<p>By default, the Dokku host may not have access to a server containing the remote repository. This can be initialized via the <code>git:allow-host</code> command.</p> <pre><code>dokku git:allow-host github.com\n</code></pre> <p>Note that this command is currently not idempotent and may add duplicate entries to the <code>~dokku/.ssh/known_hosts</code> file.</p>"},{"location":"deployment/methods/git/#creating-a-cloning-ssh-key-pair","title":"Creating a cloning ssh key pair","text":"<p>New</p> <p>Introduced in 0.33.0</p> <p>While most repositories can be authenticated to via the <code>git:auth</code> command, some users may prefer to use an ssh key. This can be generated via the <code>git:generate-deploy-key</code> command, which generates a passwordless ed25519 key-pair.</p> ShellOutput <pre><code>dokku git:generate-deploy-key\n</code></pre> <pre><code>Generating public/private ed25519 key pair.\nYour identification has been saved in /home/dokku/.ssh/id_ed25519\nYour public key has been saved in /home/dokku/.ssh/id_ed25519.pub\nThe key fingerprint is:\nSHA256:PvlvVfbpYvkmA87rTfLUq07e3GarRN1BcLqDSjod+p8 dokku@ubuntu\nThe key's randomart image is:\n+--[ED25519 256]--+\n|             ..o |\n|              +  |\n|             . . |\n|            . o =|\n|        So . + ++|\n|       .=.o.. +..|\n|       ++oo..*o. |\n|        oo o%*oo=|\n|         .+E=BOOo|\n+----[SHA256]-----+\n</code></pre>"},{"location":"deployment/methods/git/#verifying-the-cloning-public-key","title":"Verifying the cloning public key","text":"<p>In order to clone a remote repository, the remote server should have the Dokku host's public key configured. This plugin does not currently create this key, but if can be shown via the <code>git:public-key</code> command.</p> <pre><code>dokku git:public-key\n</code></pre> <p>If there is no key, an error message is shown that displays the command that can be run on the Dokku server to generate a new public/private ssh key pair.</p>"},{"location":"deployment/methods/image/","title":"Docker Image Deployment","text":""},{"location":"deployment/methods/image/#initializing-an-app-repository-from-a-docker-image","title":"Initializing an app repository from a docker image","text":"<p>New</p> <p>Introduced in 0.24.0</p> <p>A Dokku app repository can be initialized or updated from a Docker image via the <code>git:from-image</code> command. This command will either initialize the app repository or update it to include the specified Docker image via a <code>FROM</code> stanza. This is an excellent way of tracking changes when deploying only a given docker image, especially if deploying an image from a remote CI/CD pipeline.</p> <pre><code>dokku git:from-image node-js-app my-registry/node-js-getting-started:latest\n</code></pre> <p>In the above example, Dokku will build the app as if the repository contained only a <code>Dockerfile</code> with the following content:</p> <pre><code>FROM my-registry/node-js-getting-started:latest\n</code></pre> <p>If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using build phase docker-options.</p> <p>Triggering a build with the same arguments multiple times will result in Dokku exiting <code>0</code> early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:</p> <pre><code># for images pushed to a remote registry\ndocker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME\n\n# for images built locally and not pushed to a registry\n# use when the previous command output is empty\ndocker images --no-trunc --quiet $IMAGE_NAME\n</code></pre> <p>The resulting <code>git:from-image</code> call would then be:</p> <pre><code># where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\ndokku git:from-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\n</code></pre> <p>The <code>git:from-image</code> command can optionally take a git <code>user.name</code> and <code>user.email</code> argument (in that order) to customize the author. If the arguments are left empty, they will fallback to <code>Dokku</code> and <code>automated@dokku.sh</code>, respectively.</p> <pre><code>dokku git:from-image node-js-app my-registry/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>If the image is a private image that requires a docker login to access, the <code>registry:login</code> command should be used to log into the registry. See the registry documentation for more details on this process.</p> <p>Finally, certain images may require a custom build context in order for <code>ONBUILD ADD</code> and <code>ONBUILD COPY</code> statements to succeed. A custom build context can be specified via the <code>--build-dir</code> flag. All files in the specified <code>build-dir</code> will be copied into the repository for use within the <code>docker build</code> process. The build context must be specified on each deploy, and is not otherwise persisted between builds.</p> <pre><code>dokku git:from-image --build-dir path/to/build node-js-app domy-registrykku/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>See the dockerfile documentation to learn about the different ways to configure Dockerfile-based deploys.</p>"},{"location":"deployment/methods/image/#initializing-an-app-repository-from-a-remote-image-without-a-registry","title":"Initializing an app repository from a remote image without a registry","text":"<p>New</p> <p>Introduced in 0.30.0</p> <p>A Dokku app repository can be initialized or updated from the contents of an image archive tar file via the <code>git:load-image</code> command. This method can be used when a Docker Registry is unavailable to act as an intermediary for storing an image, such as when building an image in CI and deploying directly from that image.</p> <pre><code>docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest\n</code></pre> <p>In the above example, we are saving the image to a tar file via <code>docker image save</code>, streaming that to the Dokku host, and then running <code>git:load-image</code> on the incoming stream. Dokku will build the app as if the repository contained only a <code>Dockerfile</code> with the following content:</p> <pre><code>FROM my-registry/node-js-getting-started:latest\n</code></pre> <p>When deploying an app via <code>git:load-image</code>, it is highly recommended to use a unique image tag when building the image. Not doing so will result in Dokku exiting <code>0</code> early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:</p> <pre><code># for images pushed to a remote registry\ndocker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME\n\n# for images built locally and not pushed to a registry\n# use when the previous command output is empty\ndocker images --no-trunc --quiet $IMAGE_NAME\n</code></pre> <p>The resulting <code>git:load-image</code> call would then be:</p> <pre><code># where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\ndocker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\n</code></pre> <p>The <code>git:load-image</code> command can optionally take a git <code>user.name</code> and <code>user.email</code> argument (in that order) to customize the author. If the arguments are left empty, they will fallback to <code>Dokku</code> and <code>automated@dokku.sh</code>, respectively.</p> <pre><code>docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>Finally, certain images may require a custom build context in order for <code>ONBUILD ADD</code> and <code>ONBUILD COPY</code> statements to succeed. A custom build context can be specified via the <code>--build-dir</code> flag. All files in the specified <code>build-dir</code> will be copied into the repository for use within the <code>docker build</code> process. The build context must be specified on each deploy, and is not otherwise persisted between builds.</p> <pre><code>docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image --build-dir path/to/build node-js-app my-registry/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>See the dockerfile documentation to learn about the different ways to configure Dockerfile-based deploys.</p>"},{"location":"deployment/schedulers/docker-local/","title":"Docker Local Scheduler","text":"<p>New</p> <p>Subcommands introduced in 0.12.12</p> <pre><code>scheduler-docker-local:report [&lt;app&gt;] [&lt;flag&gt;]              # Displays a scheduler-docker-local report for one or more apps\nscheduler-docker-local:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)            # Set or clear a scheduler-docker-local property for an app\n</code></pre> <p>New</p> <p>Introduced in 0.12.0</p> <p>Dokku natively includes functionality to manage application lifecycles for a single server using the <code>scheduler-docker-local</code> plugin. It is the default scheduler, but as with all schedulers, it is set on a per-application basis. The scheduler can currently be overridden by running the following command:</p> <pre><code>dokku scheduler:set node-js-app selected docker-local\n</code></pre> <p>As it is the default, unsetting the <code>selected</code> scheduler property is also a valid way to reset the scheduler.</p> <pre><code>dokku scheduler:set node-js-app selected\n</code></pre>"},{"location":"deployment/schedulers/docker-local/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/docker-local/#deploying-amd64-images-on-arm64","title":"Deploying amd64 images on arm64","text":"<p>New</p> <p>Introduced in 0.33.0</p> <p>Many builders only produce amd64-compatible images. The docker-local scheduler will automatically detect these and run them via the <code>--platform=linux/amd64</code> on arm64 deploy targets.</p>"},{"location":"deployment/schedulers/docker-local/#disabling-chown-of-persistent-storage","title":"Disabling chown of persistent storage","text":"<p>The <code>scheduler-docker-local</code> plugin will ensure your storage mounts are owned by either <code>herokuishuser</code> or the overridden value you have set in <code>DOKKU_APP_USER</code>. You may disable this by running the following <code>scheduler-docker-local:set</code> command for your application:</p> <pre><code>dokku scheduler-docker-local:set node-js-app disable-chown true\n</code></pre> <p>Once set, you may re-enable it by setting a blank value for <code>disable-chown</code>:</p> <pre><code>dokku scheduler-docker-local:set node-js-app disable-chown\n</code></pre>"},{"location":"deployment/schedulers/docker-local/#disabling-the-init-process","title":"Disabling the init process","text":"<p>The <code>scheduler-docker-local</code> injects an init process by default via the <code>--init</code>. For some apps - such as those where the built docker image uses S6 as the init - this may be undesirable and cause issues with process starts. You may disable this by running the following <code>scheduler-docker-local:set</code> command for your application:</p> <pre><code>dokku scheduler-docker-local:set node-js-app init-process false\n</code></pre> <p>Once set, you may re-enable it by setting a blank value for <code>init-process</code>:</p> <pre><code>dokku scheduler-docker-local:set node-js-app init-process\n</code></pre> <p>All image containers with the label <code>org.opencontainers.image.vendor=linuxserver.io</code> will have the automatic init process injection force-disabled without further intervention.</p>"},{"location":"deployment/schedulers/docker-local/#deploying-process-types-in-parallel","title":"Deploying Process Types in Parallel","text":"<p>New</p> <p>Introduced in 0.25.5</p> <p>By default, Dokku deploys an app's processes one-by-one in order, with the <code>web</code> process being deployed first. Deployment parallelism may be achieved by setting the <code>parallel-schedule-count</code> property, which defaults to <code>1</code>. Increasing this number increases the number of process types that may be deployed in parallel (with the web process being the exception).</p> <pre><code># Increase parallelism from 1 process type at a time to 4 process types at a time.\ndokku scheduler-docker-local:set node-js-app parallel-schedule-count 4\n</code></pre> <p>Once set, you may reset it by setting a blank value for <code>parallel-schedule-count</code>:</p> <pre><code>dokku scheduler-docker-local:set node-js-app parallel-schedule-count\n</code></pre> <p>If the value of <code>parallel-schedule-count</code> is increased and a given process type fails to schedule successfully, then any in-flight process types will continue to be processed, while all process types that have not been scheduled will be skipped before the deployment finally fails.</p> <p>Container scheduling output is shown in the order it is received, and thus may be out of order in case of output to stderr.</p> <p>Note that increasing the value of <code>parallel-schedule-count</code> may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.</p>"},{"location":"deployment/schedulers/docker-local/#increasing-parallelism-within-a-process-deploy","title":"Increasing parallelism within a process deploy","text":"<p>New</p> <p>Introduced in 0.26.0</p> <p>By default, Dokku will deploy one instance of a given process type at a time. This can be increased by customizing the <code>app.json</code> <code>formation</code> key to include a <code>max_parallel</code> key for the given process type.</p> <p>The <code>formation</code> key should be specified as follows in the <code>app.json</code> file:</p> <pre><code>{\n  \"formation\": {\n    \"web\": {\n      \"max_parallel\": 1\n    },\n    \"worker\": {\n      \"max_parallel\": 4\n    }\n  }\n}\n</code></pre> <p>Omitting or removing the entry will result in parallelism for that process type to return to 1 entry at a time. This can be combined with the <code>parallel-schedule-count</code> property to speed up deployments.</p> <p>Note that increasing the value of <code>max_parallel</code> may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.</p> <p>See the app.json location documentation for more information on where to place your <code>app.json</code> file.</p>"},{"location":"deployment/schedulers/docker-local/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented scheduler functionality for the <code>docker-local</code> scheduler.</p>"},{"location":"deployment/schedulers/docker-local/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the <code>scheduler-docker-local</code> plugin.</p> <ul> <li><code>apps:clone</code></li> <li><code>apps:destroy</code></li> <li><code>apps:rename</code></li> <li><code>deploy</code></li> <li><code>enter</code></li> <li><code>logs</code></li> <li><code>ps:inspect</code></li> <li><code>ps:stop</code></li> <li><code>run</code></li> </ul>"},{"location":"deployment/schedulers/docker-local/#logging-support","title":"Logging support","text":"<p>App logs for the <code>logs</code> command are fetched from running containers via the <code>docker</code> cli. To persist logs across deployments, consider using Dokku's vector integration to ship logs to another service or a third-party platform.</p>"},{"location":"deployment/schedulers/docker-local/#supported-resource-management-properties","title":"Supported Resource Management Properties","text":"<p>The <code>docker-local</code> scheduler supports a minimal list of resource limits and reservations. The following properties are supported:</p>"},{"location":"deployment/schedulers/docker-local/#resource-limits","title":"Resource Limits","text":"<ul> <li>cpu: (docker option: <code>--cpus</code>), is specified in number of CPUs a process can access.<ul> <li>See the \"CPU\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> <li>memory: (docker option: <code>--memory</code>) should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).<ul> <li>See the \"Memory\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> <li>memory-swap: (docker option: <code>--memory-swap</code>) should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes)<ul> <li>See the \"Memory\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> <li>nvidia-gpus: (docker option: <code>--gpus</code>), is specified in number of Nvidia GPUs a process can access.<ul> <li>See the \"GPU\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> </ul>"},{"location":"deployment/schedulers/docker-local/#resource-reservations","title":"Resource Reservations","text":"<ul> <li>memory: (docker option: <code>--memory-reservation</code>) should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).<ul> <li>See the \"Memory\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> </ul>"},{"location":"deployment/schedulers/k3s/","title":"K3s Scheduler","text":"<pre><code>scheduler-k3s:initialize                           # initializes a cluster\nscheduler-k3s:add-server [user:password@host:port] # adds a server node to a Dokku-managed cluster\nscheduler-k3s:add-client [user:password@host:port] # adds a client node to a Dokku-managed cluster\nscheduler-k3s:set [&lt;app&gt;|--global] &lt;key&gt; (&lt;value&gt;) # Set or clear a scheduler-k3s property for an app or the scheduler\n</code></pre> <p>New</p> <p>Introduced in 0.33.0</p> <p>For multi-server support, Dokku provides the ability for users to setup a K3s cluster. As with all schedulers, it is set on a per-app basis. The scheduler can currently be overridden by running the following command:</p> <pre><code>dokku scheduler:set node-js-app selected k3s\n</code></pre> <p>As it is the default, unsetting the <code>selected</code> scheduler property is also a valid way to reset the scheduler.</p> <pre><code>dokku scheduler:set node-js-app k3s\n</code></pre>"},{"location":"deployment/schedulers/k3s/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/k3s/#initializing-a-cluster","title":"Initializing a cluster","text":"<p>Warning</p> <p>This command must be run as root</p> <p>Clusters can be initialized via the <code>scheduler-k3s:initialize</code> command. This will start a k3s cluster on the Dokku node itself.</p> <pre><code>dokku scheduler-k3s:initialize\n</code></pre> <p>By default, the k3s installation can run both app and system workloads. For clusters where app workloads are run on distinct worker nodes, initialize the cluster with the <code>--taint-scheduling</code> flag, which will allow only Critical cluster components on the k3s control-plane nodes.</p> <pre><code>dokku scheduler-k3s:initialize --taint-scheduling\n</code></pre> <p>By default, Dokku will attempt to auto-detect the IP address of the server. In cases where the auto-detected IP address is incorrect, an override may be specified via the <code>--server-ip</code> flag:</p> <pre><code>dokku scheduler-k3s:initialize --server-ip 192.168.20.15\n</code></pre>"},{"location":"deployment/schedulers/k3s/#adding-nodes-to-the-cluster","title":"Adding nodes to the cluster","text":"<p>Warning</p> <p>The <code>dokku</code> user must be able to ssh onto the server in order to connect nodes to the cluster. The remote user must be root or have sudo enabled, or the install will fail.</p>"},{"location":"deployment/schedulers/k3s/#adding-a-worker-node","title":"Adding a worker node","text":"<p>Nodes that run app workloads can be added via the <code>scheduler-k3s:cluster-add</code> command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.</p> <pre><code>dokku scheduler-k3s:cluster-add  ssh://root@worker-1.example.com\n</code></pre> <p>If the server isn't in the <code>known_hosts</code> file, the connection will fail. This can be bypassed by setting the <code>--insecure-allow-unknown-hosts</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --insecure-allow-unknown-hosts ssh://root@worker-1.example.com\n</code></pre> <p>By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the <code>--server-ip</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --server-ip 192.168.20.15 ssh://root@worker-1.example.com\n</code></pre>"},{"location":"deployment/schedulers/k3s/#adding-a-server-node","title":"Adding a server node","text":"<p>Note</p> <p>Only the initial Dokku server will be properly configured for push deployment, and should be considered your git remote. Additional server nodes are for ensuring high-availability of the K3s etcd state. Ensure this server is properly backed up and restorable or deployments will not work.</p> <p>Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.</p> <p>Server nodes can also be added with the <code>scheduler-k3s:cluster-add</code> command by specifying <code>--role server</code>. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.</p> <pre><code>dokku scheduler-k3s:cluster-add  --role server ssh://root@server-1.example.com\n</code></pre> <p>Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the <code>--taint-scheduling</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com\n</code></pre> <p>If the server isn't in the <code>known_hosts</code> file, the connection will fail. This can be bypassed by setting the <code>--insecure-allow-unknown-hosts</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@server-1.example.com\n</code></pre> <p>By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the <code>--server-ip</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --server-ip 192.168.20.15 ssh://root@server-1.example.com\n</code></pre>"},{"location":"deployment/schedulers/k3s/#changing-the-network-interface","title":"Changing the network interface","text":"<p>When attaching an worker or server node, the K3s plugin will look at the IP associated with the <code>eth0</code> interface and use that to connect the new node to the cluster. To change this, set the <code>network-interface</code> property to the appropriate value.</p> <pre><code>dokku scheduler-k3s:set --global network-interface eth1\n</code></pre>"},{"location":"deployment/schedulers/k3s/#changing-deploy-timeouts","title":"Changing deploy timeouts","text":"<p>By default, app deploys will timeout after 300s. To customize this value, set the <code>deploy-timeout</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app deploy-timeout 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app deploy-timeout\n</code></pre> <p>The <code>deploy-timeout</code> property can also be set globally. The global default is <code>300s</code>.</p> <pre><code>dokku scheduler-k3s:set --global deploy-timeout 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global deploy-timeout\n</code></pre>"},{"location":"deployment/schedulers/k3s/#customizing-the-namespace","title":"Customizing the namespace","text":"<p>By default, app deploys will run against the <code>default</code> Kubernetes namespace. To customize this value, set the <code>namespace</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app namespace lollipop\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app namespace\n</code></pre> <p>The <code>namespace</code> property can also be set globally. The global default is <code>default</code>.</p> <pre><code>dokku scheduler-k3s:set --global namespace 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global namespace\n</code></pre>"},{"location":"deployment/schedulers/k3s/#enabling-rollback-on-failure","title":"Enabling rollback on failure","text":"<p>By default, app deploys do not rollback on failure. To enable this functionality, set the <code>rollback-on-failure</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app rollback-on-failure true\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app rollback-on-failure\n</code></pre> <p>The <code>rollback-on-failure</code> property can also be set globally. The global default is <code>false</code>.</p> <pre><code>dokku scheduler-k3s:set --global rollback-on-failure false\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global rollback-on-failure\n</code></pre>"},{"location":"deployment/schedulers/k3s/#using-image-pull-secrets","title":"Using image pull secrets","text":"<p>When authenticating against a registry via <code>registry:login</code>, the scheduler-k3s plugin will authenticate all servers in the cluster against the registry specified. If desired, an image pull secret can be used instead. To customize this value, set the <code>image-pull-secrets</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app image-pull-secrets lollipop\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app image-pull-secrets\n</code></pre> <p>The <code>image-pull-secrets</code> property can also be set globally. The global default is empty string, and k3s will use the local <code>registries.yaml</code> for any private registry pulls.</p> <pre><code>dokku scheduler-k3s:set --global image-pull-secrets 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global image-pull-secrets\n</code></pre>"},{"location":"deployment/schedulers/k3s/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email-prod</code> or <code>letsencrypt-email-stag</code> property with the <code>--global</code> flag:</p> <pre><code># set the value for prod\ndokku scheduler-k3s:set --global letsencrypt-email-prod automated@dokku.sh\n\n# set the value for stag\ndokku scheduler-k3s:set --global letsencrypt-email-stag automated@dokku.sh\n</code></pre> <p>After enabling, all apps with an <code>https</code> port mapping that utilize the related letsencrypt server will be automatically updated to enable ssl. All http requests will then be redirected to https.</p>"},{"location":"deployment/schedulers/k3s/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. This can be changed on an app-level by setting the <code>letsencrypt-server</code> property with the <code>scheduler-k3s:set</code> command</p> <pre><code>dokku scheduler-k3s:set node-js-app letsencrypt-server staging\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app letsencrypt-server\n</code></pre> <p>The <code>image-pull-secrets</code> property can also be set globally. The global default is <code>production</code>.</p> <pre><code>dokku scheduler-k3s:set --global letsencrypt-server staging\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global letsencrypt-server staging\n</code></pre> <p>After changing, all apps with an</p>"},{"location":"deployment/schedulers/k3s/#using-kubectl-remotely","title":"Using kubectl remotely","text":"<p>Warning</p> <p>Certain ports must be open for interacting with the remote kubernets api. Refer to the K3s networking documentation for the required open ports between servers prior to running the command.</p> <p>By default, Dokku assumes that all it controls all actions on the cluster, and thus does not expose the <code>kubectl</code> binary for administrators. To interact with kubectl, you will need to retrieve the <code>kubeconfig</code> for the cluster and configure your client to use that configuration.</p> <pre><code>dokku scheduler-k3s:show-kubeconfig\n</code></pre>"},{"location":"deployment/schedulers/k3s/#tutorial","title":"Tutorial","text":""},{"location":"deployment/schedulers/k3s/#single-node-cluster","title":"Single-node cluster","text":"<p>Initialize the cluster in single-node mode. This will start k3s on the Dokku node itself.</p> <pre><code># must be run as root\ndokku scheduler-k3s:initialize\n</code></pre> <p>The above command will initialize a cluster with the following configuration:</p> <ul> <li>etcd distributed backing store</li> <li>Wireguard as the networking flannel</li> <li>K3s automatic upgrader</li> <li>Longhorn distributed block storage</li> <li>Traefik configured to run on all nodes in the cluster</li> </ul> <p>Additionally, an internal token for authentication will be automatically generated. This token should be stored securely for later recovery, and can be displayed with via the <code>scheduler-k3s:report</code> command:</p> ShellOutput <pre><code>dokku scheduler-k3s:report --global\n</code></pre> <pre><code>=====&gt; --global scheduler-k3s information\n       scheduler k3s token: topsecret:server:token\n</code></pre> <p>Setup registry authentication. The K3s scheduler plugin will automatically pick up any newly configured registry backends and ensure nodes in the cluster have the credentials in place for pulling images from the cluster.</p> <pre><code># hub.docker.com\ndokku registry:login hub.docker.com $USERNAME $PASSWORD\n</code></pre> <p>To ensure images are pushed and pulled from the correct registry, set the correct <code>server</code> registry property. This can be set on a per-app basis, but we will set it globally here for this tutorial.</p> <pre><code>dokku registry:set --global server hub.docker.com\n</code></pre> <p>If using docker hub, you'll need to use a custom repository name. This can be set via a global template, allowing users access to the app name as the variable <code>AppName</code> as shown below.</p> <pre><code>dokku registry:set --global image-repo-template \"my-awesome-prefix/{{ .AppName }}\"\n</code></pre> <p>Additionally, apps should be configured to push images on the release phase via the <code>push-on-release</code> registry property.</p> <pre><code>dokku registry:set --global push-on-release true\n</code></pre> <p>As routing is handled by traefik managed on the k3s plugin, set the proxy plugin to <code>k3s</code> as well.</p> <pre><code>dokku proxy:set --global k3s\n</code></pre> <p>Ensure any other proxy implementations are disabled. Typically at least nginx will be running on the Dokku host and should be stopped if the host is used as load balancer.</p> <pre><code>dokku nginx:stop\n</code></pre> <p>Finally, set the scheduler to <code>k3s</code> so that app deploys will work on k3s.</p> <pre><code>dokku scheduler:set --global selected k3s\n</code></pre> <p>At this point, all app deploys will be performed against the k3s cluster.</p> <p>Note</p> <p>HTTP requests for apps can be performed against any node in the cluster. Without extra configuration, many other ports may also be available on the host. For security reasons, it may be desirable to place the k3s cluster behind one or more TCP load balancers while shutting off traffic to all cluster ports. Please consult your hosting provider for more information on how to provision a TCP load balancer and shut off all ports other than 22/80/443 access to the outside world.</p>"},{"location":"deployment/schedulers/k3s/#running-a-multi-cluster-node","title":"Running a multi-cluster node","text":"<p>Warning</p> <p>Certain ports must be open for cross-server communication. Refer to the K3s networking documentation for the required open ports between servers prior to running the command.</p> <p>For high-availability, it is recommended to add both worker and server nodes to the cluster. Dokku will default to starting the cluster with an embedded Etcd database backend, and is ready to add new worker or server nodes immediately.</p> <p>When attaching an worker or server node, the K3s plugin will look at the IP associated with the <code>eth0</code> interface and use that to connect the new node to the cluster. To change this, set the <code>network-interface</code> property to the appropriate value.</p> <pre><code>dokku scheduler-k3s:set --global network-interface eth1\n</code></pre> <p>Dokku will connect to remote servers via the <code>root</code> user with the <code>dokku</code> user's SSH key pair. Dokku servers may not have an ssh key pair by default, but they can be generated as needed via the <code>git:generate-deploy-key</code> command.</p> <pre><code>dokku git:generate-deploy-key\n</code></pre> <p>This key can then be displayed with the <code>git:public-key</code> command, and copied to the remote server's <code>/root/.ssh/authorized_keys</code> file.</p> <pre><code>dokku git:public-key\n</code></pre> <p>Multiple server nodes can be added with the <code>scheduler-k3s:cluster-add</code> command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.</p> <pre><code>dokku scheduler-k3s:cluster-add  --role server ssh://root@server-1.example.com\n</code></pre> <p>Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the <code>--taint-scheduling</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com\n</code></pre> <p>If the server isn't in the <code>known_hosts</code> file, the connection will fail. This can be bypassed by setting the <code>--insecure-allow-unknown-hosts</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@worker-1.example.com\n</code></pre> <p>Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.</p> <p>Note</p> <p>Only the initial Dokku server will be properly configured for push deployment, and should be considered your git remote. Additional server nodes are for ensuring high-availability of the K3s etcd state. Ensure this server is properly backed up and restorable or deployments will not work.</p> <p>Worker nodes are used to run. To add an worker, run the <code>scheduler-k3s:cluster-add</code> with the <code>--role worker</code> flag. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.</p> <pre><code>dokku scheduler-k3s:cluster-add --role worker ssh://root@worker-1.example.com\n</code></pre>"},{"location":"deployment/schedulers/k3s/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented and unimplemented scheduler functionality for the <code>k3s</code> scheduler.</p>"},{"location":"deployment/schedulers/k3s/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the <code>scheduler-k3s</code> plugin.</p> <ul> <li><code>apps:clone</code></li> <li><code>apps:destroy</code></li> <li><code>apps:rename</code></li> <li><code>cron</code></li> <li><code>enter</code></li> <li><code>deploy</code></li> <li>healthchecks<ul> <li>Due to Kubernetes limitations, only a single healthcheck is supported for each of the <code>liveness</code>, <code>readiness</code>, and <code>startup</code> healthchecks</li> <li>Due to Kubernetes limitations, content checks are not supported</li> <li>Ports specified in the <code>app.json</code> are ignored in favor of the container port on the port mapping detected</li> </ul> </li> <li><code>logs</code></li> <li><code>ps:stop</code></li> <li><code>run</code><ul> <li>The <code>scheduler-post-run</code> trigger is not always triggered</li> </ul> </li> <li><code>run:detached</code></li> <li><code>run:list</code></li> </ul>"},{"location":"deployment/schedulers/k3s/#unimplemented-command-functionality","title":"Unimplemented command functionality","text":"<ul> <li><code>run:logs</code></li> <li><code>ps:inspect</code></li> </ul> <p>The following Dokku functionality is not implemented at this time.</p> <ul> <li><code>vector</code> log integration</li> <li>persistent storage</li> </ul>"},{"location":"deployment/schedulers/k3s/#logging-support","title":"Logging support","text":"<p>App logs for the <code>logs</code> command are fetched by Dokku from running containers via the <code>kubectl</code> cli. Persisting logs via Vector is not implemented at this time. Users may choose to configure the Vector Kubernetes integration directly by following this guide.</p>"},{"location":"deployment/schedulers/k3s/#supported-resource-management-properties","title":"Supported Resource Management Properties","text":"<p>The <code>k3s</code> scheduler supports a minimal list of resource limits and reservations. The following properties are supported:</p>"},{"location":"deployment/schedulers/k3s/#resource-limits","title":"Resource Limits","text":"<p>Note</p> <p>Cron tasks retrieve resource limits based on the computed cron task ID. If unspecified, the default will be 1 CPU and 512m RAM.</p> <ul> <li>cpu: is specified in number of CPUs a process can access.</li> <li>memory: should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).</li> </ul>"},{"location":"deployment/schedulers/k3s/#resource-reservations","title":"Resource Reservations","text":"<p>Note</p> <p>Cron tasks retrieve resource reservations based on the computed cron task ID. If unspecified, the default will be 1 CPU and 512m RAM.</p> <ul> <li>cpu: is specified in number of CPUs a process can access.</li> <li>memory: should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).</li> </ul>"},{"location":"deployment/schedulers/kubernetes/","title":"Kubernetes Scheduler","text":"<p>Warning</p> <p>This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.</p> <p>The Kubernetes Scheduler Plugin is available free as an external plugin. Please see the plugin's issue tracker for more information on the status of the plugin.</p> <p>For users that require additional functionality, please refer to the Sponsoring Documentation.</p>"},{"location":"deployment/schedulers/kubernetes/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented scheduler functionality for the <code>kubernetes</code> scheduler.</p>"},{"location":"deployment/schedulers/kubernetes/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with <code>kubectl</code> for running apps on a Kubernetes cluster. The following functionality is supported by the <code>scheduler-kubernetes</code> plugin.</p> <ul> <li><code>apps:destroy</code></li> <li><code>deploy</code>: partial, does not implement failed deploy log capture</li> <li><code>logs</code>: partial, does not implement failure logs</li> <li><code>ps:stop</code></li> </ul>"},{"location":"deployment/schedulers/kubernetes/#logging-support","title":"Logging support","text":"<p>App logs for the <code>logs</code> command are fetched from running pods via the <code>kubectl</code> cli. To persist logs across deployments, consider using Vector or a similar tool to ship logs to another service or a third-party platform.</p>"},{"location":"deployment/schedulers/nomad/","title":"Nomad Scheduler","text":"<p>Warning</p> <p>This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.</p> <p>The Nomad Scheduler Plugin is available free as an external plugin. Please see the plugin's issue tracker for more information on the status of the plugin.</p> <p>For users that require additional functionality, please refer to the Sponsoring Documentation.</p>"},{"location":"deployment/schedulers/nomad/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented scheduler functionality for the <code>nomad</code> scheduler.</p>"},{"location":"deployment/schedulers/nomad/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with the <code>nomad</code> cli for running apps on a Nomad cluster. The following functionality is supported by the <code>scheduler-nomad</code> plugin.</p> <ul> <li><code>apps:destroy</code></li> <li><code>deploy</code></li> <li><code>ps:stop</code></li> </ul>"},{"location":"deployment/schedulers/nomad/#logging-support","title":"Logging support","text":""},{"location":"deployment/schedulers/null/","title":"Null Scheduler","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>The <code>null</code> scheduler does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the network documentation for more information on the aforementioned use case.</p>"},{"location":"deployment/schedulers/null/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/null/#detection","title":"Detection","text":"<p>This scheduler is never auto-detected. The scheduler must  be specified via the <code>scheduler:set</code> command:</p> <pre><code>dokku scheduler:set node-js-app selected null\n</code></pre>"},{"location":"deployment/schedulers/scheduler-management/","title":"Scheduler Management","text":"<p>New</p> <p>Introduced in 0.26.0</p> <pre><code>scheduler:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a scheduler report for one or more apps\nscheduler:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a scheduler property for an app\n</code></pre> <p>Schedulers are a way of customizing how an app image is deployed, and can be used to interact with non-local systems such as Kubernetes and Nomad.</p>"},{"location":"deployment/schedulers/scheduler-management/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/scheduler-management/#scheduler-selection","title":"Scheduler selection","text":"<p>Dokku supports the following built-in schedulers:</p> <ul> <li><code>scheduler-docker-local</code>: Schedules apps against the local docker socket and runs containers directly on the Dokku host. See the docker-local scheduler documentation for more information on how this scheduler functions.</li> <li><code>scheduler-null</code>: Does nothing during the scheduler phase. See the null scheduler documentation for more information on how this scheduler functions.</li> </ul>"},{"location":"deployment/schedulers/scheduler-management/#overriding-the-auto-selected-scheduler","title":"Overriding the auto-selected scheduler","text":"<p>If desired, the scheduler can be specified via the <code>scheduler:set</code> command by speifying a value for <code>selected</code>. The selected scheduler will always be used.</p> <pre><code>dokku scheduler:set node-js-app selected docker-local\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler:set node-js-app selected\n</code></pre> <p>The <code>selected</code> property can also be set globally. The global default is an empty string, and auto-detection will be performed when no value is set per-app or globally.</p> <pre><code>dokku scheduler:set --global selected docker-local\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler:set --global selected\n</code></pre>"},{"location":"deployment/schedulers/scheduler-management/#displaying-scheduler-reports-for-an-app","title":"Displaying scheduler reports for an app","text":"<p>You can get a report about the app's scheduler status using the <code>scheduler:report</code> command:</p> ShellOutput <pre><code>dokku scheduler:report\n</code></pre> <pre><code>=====&gt; node-js-app scheduler information\n       Scheduler computed selected:  herokuish\n       Scheduler global selected: herokuish\n       Scheduler selected: herokuish\n=====&gt; python-sample scheduler information\n       Scheduler computed selected: dockerfile\n       Scheduler global selected: herokuish\n       Scheduler selected: dockerfile\n=====&gt; ruby-sample scheduler information\n       Scheduler computed selected: herokuish\n       Scheduler global selected: herokuish\n       Scheduler selected:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku scheduler:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app scheduler information\n       Scheduler selected: herokuish\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku scheduler:report node-js-app --scheduler-selected\n</code></pre>"},{"location":"deployment/schedulers/scheduler-management/#implementing-a-scheduler","title":"Implementing a Scheduler","text":"<p>Custom plugins names must have the prefix <code>scheduler-</code> or scheduler overriding via <code>scheduler:set</code> may not function as expected.</p> <p>At this time, the following dokku commands are used to implement a complete scheduler.</p> <ul> <li><code>apps:destroy</code>: stops the app processes on the scheduler<ul> <li>triggers: post-delete, scheduler-register-retired, scheduler-retire</li> </ul> </li> <li><code>apps:rename</code>: handles app renaming<ul> <li>triggers: post-app-rename-setup</li> </ul> </li> <li><code>apps:clone</code>: handles app cloning<ul> <li>triggers: post-app-clone-setup</li> </ul> </li> <li><code>cron</code>: generates cron tasks for the app<ul> <li>triggers: cron-write</li> </ul> </li> <li><code>deploy</code>: deploys app proceses and checks the status of a deploy<ul> <li>triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed</li> </ul> </li> <li><code>enter</code>: enters a running container<ul> <li>triggers: scheduler-enter</li> </ul> </li> <li><code>logs</code>: fetches app logs<ul> <li>triggers: scheduler-logs</li> </ul> </li> <li><code>run</code>: starts one-off run containers (detached and non-detached) as well as listing run processes<ul> <li>triggers: scheduler-run, scheduler-run-list</li> </ul> </li> <li><code>run:list</code>: lists running containers<ul> <li>triggers: scheduler-run-list</li> </ul> </li> <li><code>run:logs</code>: fetches running container logs<ul> <li>triggers: scheduler-run-logs</li> </ul> </li> <li><code>ps:stop</code>: stops app processes<ul> <li>triggers: scheduler-stop</li> </ul> </li> <li><code>ps:inspect</code>: outputs inspect output for processes in an app<ul> <li>triggers: scheduler-inspect</li> </ul> </li> </ul> <p>Schedulers may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins. Additionally, a scheduler may implement other triggers in order handle any extra processes needed during a deploy.</p> <p>Schedulers can use any tools available on the system to build the docker image, and may even be used to interact with off-server systems. The only current requirement is that the scheduler must have access to the image built in the build phase. If this is not the case, the registry plugin can be used to push the image to a registry that the scheduler software can access.</p> <p>Deployment tasks are currently executed directly on the primary Dokku server.</p>"},{"location":"development/plugin-creation/","title":"Plugin creation","text":"<p>A plugin can be a simple implementation of triggers or can implement a command structure of its own. Dokku has no restrictions on the language in which a plugin is implemented; it only cares that the plugin implements the appropriate commands or triggers for the API. NOTE: any file that implements triggers or uses the command API must be executable.</p>"},{"location":"development/plugin-creation/#plugin-overview","title":"Plugin Overview","text":"<p>When creating custom plugins:</p> <ol> <li>Take a look at the plugins shipped with Dokku and hack away!</li> <li>Check out the list of triggers the plugin can implement</li> <li>Upload the plugin to GitHub with a repository name following the <code>dokku-&lt;name&gt;</code> convention (e.g. <code>dokku-mariadb</code>)</li> <li>Edit this page and add a link to the plugin</li> <li>Subscribe to the dokku development blog to be notified about API changes and releases</li> </ol>"},{"location":"development/plugin-creation/#compilable-plugins-golang-java-c-etc","title":"Compilable plugins (Golang, Java(?), C, etc.)","text":"<p>When developing a plugin, the <code>install</code> trigger must be implemented such that it outputs the built executable(s) using a directory structure that implements the plugin's desired command and/or triggers the API. See the smoke-test-plugin for an example.</p>"},{"location":"development/plugin-creation/#command-api","title":"Command API","text":"<p>There are 3 main integration points: <code>commands</code>, <code>subcommands/default</code>, and <code>subcommands/&lt;command-name&gt;</code>.</p>"},{"location":"development/plugin-creation/#commands","title":"<code>commands</code>","text":"<p>Primarily used to supply the plugin's usage/help output. (i.e. plugin help).</p>"},{"location":"development/plugin-creation/#subcommandsdefault","title":"<code>subcommands/default</code>","text":"<p>Implements the plugin's default command behavior. (i.e. <code>dokku plugin</code>).</p>"},{"location":"development/plugin-creation/#subcommandscommand-name","title":"<code>subcommands/&lt;command-name&gt;</code>","text":"<p>Implements the additional command interface and will translate to <code>dokku plugin:cmd</code> on the command line. (i.e. <code>dokku plugin:install</code>).</p>"},{"location":"development/plugin-creation/#plugin-building-tips","title":"Plugin Building Tips","text":""},{"location":"development/plugin-creation/#always-create-a-plugintoml","title":"Always create a <code>plugin.toml</code>","text":"<p>The <code>plugin.toml</code> file is used to describe the plugin in help output, and helps users understand the purpose of the plugin. This must have a description and a version. The version should be bumped at every plugin release.</p> <pre><code>[plugin]\ndescription = \"dokku example plugin\"\nversion = \"0.1.0\"\n[plugin.config]\n</code></pre>"},{"location":"development/plugin-creation/#files-should-be-executable","title":"Files should be executable","text":"<p>Commands, subcommands, triggers and source shell scripts should all be executable. On a Unix-like machine, the following command can be used to make them executable:</p> <pre><code>chmod +x path/to/file\n</code></pre> <p>Non-executable commands, subcommands, and triggers will be ignored.</p>"},{"location":"development/plugin-creation/#use-the-pipefail-bash-option","title":"Use the <code>pipefail</code> bash option","text":"<p>Consider whether to include the <code>set -eo pipefail</code> option. Look at the following example:</p> <pre><code>IMAGE=$(docker images | grep \"user/repo\" | awk '{print $3}')\nif [[ -z $IMAGE ]]; then\n  dokku_log_fail \"user/repo image not found... Did you run 'dokku plugin:install'?\"\nfi\n</code></pre> <p>If <code>user/repo</code> doesn't exist, Dokku exits just before the <code>awk</code> command and the <code>dokku_log_fail</code> message will never go to <code>STDOUT</code>. printed with echo. The <code>set -e</code> option should be used in this case.</p> <p>Here is the <code>help</code> entry for <code>set</code>:</p> <pre><code>help set\nOptions:\n  -e  Exit immediately if a command exits with a non-zero status.\n  -o option-name\n      pipefail     the return value of a pipeline is the status of\n                   the last command to exit with a non-zero status,\n                   or zero if no command exited with a non-zero status\n</code></pre>"},{"location":"development/plugin-creation/#support-trace-mode","title":"Support trace mode","text":"<p>Trace mode is useful for getting debugging output from plugins when the <code>--trace</code> flag is specified or <code>dokku trace:on</code> is triggered. This should be done at the top of each shell script:</p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\n</code></pre> <p>In the above example, the third line enables bash's debug mode, which prints command traces before executing command.</p>"},{"location":"development/plugin-creation/#verify-the-existence-of-dependencies","title":"Verify the existence of dependencies","text":"<p>If a plugin depends on a specific command-line tool, check whether that tool exists before utilizing it. Either <code>command -v</code> or <code>which</code> may be used to do so:</p> <pre><code># `command -v` example\nif ! command -v \"nginx\" &amp;&gt;/dev/null; then\n  dokku_log_fail \"Missing nginx, install it\"\nfi\n\n# `which` example\nif ! which nginx &amp;&gt;/dev/null; then\n  dokku_log_fail \"Missing nginx, install it\"\nfi\n</code></pre> <p>In cases where a dependency should be installed before the plugin can be used at all, use the <code>dependencies</code> plugin trigger to install the dependency.</p>"},{"location":"development/plugin-creation/#implement-a-help-command","title":"Implement a help command","text":"<p>For plugins which expose commands, implement a <code>help</code> command. This may be empty, but should contain a listing of all available commands.</p> <p>Commas - <code>,</code> - are used in the help output for columnizing output. Verify that the plugin conforms to the spec by running <code>dokku help --all</code> and manually verifying the output.</p> <p>See the sample plugin below for an example.</p>"},{"location":"development/plugin-creation/#namespace-commands","title":"Namespace commands","text":"<p>All commands should be namespaced. In cases where a core plugin is overriden, the plugin may utilize the a namespace in use by the core, but generally this should be avoided to reduce confusion as to where the command is implemented.</p>"},{"location":"development/plugin-creation/#implement-a-proper-catch-all-command","title":"Implement a proper catch-all command","text":"<p>As of 0.3.3, a catch-all should be implemented that exits with a <code>DOKKU_NOT_IMPLEMENTED_EXIT</code> code. This allows Dokku to output a <code>command not found</code> message.</p> <p>See the sample plugin below for an example.</p>"},{"location":"development/plugin-creation/#set-app-config-without-restarting","title":"Set app config without restarting","text":"<p>In the case that a plugin needs to set app configuration settings and a restart should be avoided (default Heroku-style behavior) these \"internal\" commands provide this functionality:</p> <pre><code>config_set --no-restart node-js-app KEY1=VALUE1 [KEY2=VALUE2 ...]\nconfig_unset --no-restart node-js-app KEY1 [KEY2 ...]\n</code></pre>"},{"location":"development/plugin-creation/#expose-functionality-in-a-functions-file","title":"Expose functionality in a <code>functions</code> file","text":"<p>To allow other plugins access to (some of) a plugin's functionality, functions can expose by including a <code>functions</code> file in the plugin for others to source. All functions in that file should be considered publicly accessible by other plugins.</p> <p>Any functions that must be kept private should reside in the plugin's <code>trigger/</code> or <code>commands/</code> directories. Other files may also be used to hide private functions; the official convention for hiding private functions is to place them an <code>internal-functions</code> file.</p>"},{"location":"development/plugin-creation/#use-helper-functions-to-fetch-app-images","title":"Use helper functions to fetch app images","text":"<p>New</p> <p>Introduced in 0.4.0</p> <p>Dokku allows image tagging and deployment of tagged images. This means hard-coding the <code>$IMAGE</code> as <code>dokku/$APP</code> is no longer sufficient.</p> <p>Plugins should use <code>get_running_image_tag()</code> and <code>get_app_image_name()</code> as sourced from <code>common/functions</code>. See the plugin triggers doc for examples.</p> <p>Info</p> <p>Note: This is only for plugins that are not <code>pre/post-build-*</code> plugins</p>"},{"location":"development/plugin-creation/#use-docker_bin-instead-of-docker-directly","title":"Use <code>$DOCKER_BIN</code> instead of <code>docker</code> directly","text":"<p>New</p> <p>Introduced in 0.17.5</p> <p>Certain systems may require a wrapper function around the <code>docker</code> binary for proper execution. Utilizing the <code>$DOCKER_BIN</code> environment variable when calling docker for those functions is preferred.</p> <pre><code># good\n\"$DOCKER_BIN\" container run -d $IMAGE /bin/bash -e -c \"$COMMAND\"\n\n# bad\ndocker run -d $IMAGE /bin/bash -e -c \"$COMMAND\"\n</code></pre>"},{"location":"development/plugin-creation/#include-labels-for-all-temporary-containers-and-images","title":"Include labels for all temporary containers and images","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>As of 0.5.0, labels are used to help cleanup intermediate containers with <code>dokku cleanup</code>. Plugins that create containers and images should add the correct labels to the <code>build</code>, <code>commit</code>, and <code>run</code> docker commands.</p> <p>Note that where possible, a label <code>com.dokku.app-name=$APP</code> - where <code>$APP</code> is the name of the app - should also be included. This enables <code>dokku cleanup APP</code> to cleanup the specific containers for a given app.</p> <pre><code># `docker build` example\n\"$DOCKER_BIN\" image build \"--label=com.dokku.app-name=${APP}\" $DOKKU_GLOBAL_BUILD_ARGS ...\n\n# `docker commit` example\n# Note that the arguments must be set as a local array\n# as arrays cannot be exported in shell\nlocal DOKKU_COMMIT_ARGS=(\"--change\" \"LABEL org.label-schema.schema-version=1.0\" \"--change\" \"LABEL org.label-schema.vendor=dokku\" \"--change\" \"LABEL $DOKKU_CONTAINER_LABEL=\")\n\"$DOCKER_BIN\" container commit --change \"LABEL com.dokku.app-name=$APP\" \"${DOKKU_COMMIT_ARGS[@]}\" ...\n\n# `docker run` example\n\"$DOCKER_BIN\" container run \"--label=com.dokku.app-name=${APP}\" $DOKKU_GLOBAL_RUN_ARGS ...\n</code></pre>"},{"location":"development/plugin-creation/#copy-files-from-the-built-image-using-copy_from_image","title":"Copy files from the built image using <code>copy_from_image</code>","text":"<p>Avoid copying files from running containers as these files may change over time. Instead copy files from the image built during the deploy process. This can be done via the <code>copy_from_image</code> helper function. This will correctly handle various corner cases in copying files from an image.</p> <pre><code>source \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nlocal TMP_FILE=$(mktemp \"/tmp/dokku-${DOKKU_PID}-${FUNCNAME[0]}.XXXXXX\")\ntrap \"rm -rf '$TMP_FILE' &gt;/dev/null\" RETURN INT TERM EXIT\n\nlocal IMAGE_TAG=\"$(get_running_image_tag \"$APP\")\"\nlocal IMAGE=$(get_deploying_app_image_name \"$APP\" \"$IMAGE_TAG\")\ncopy_from_image \"$IMAGE\" \"file-being-copied\" \"$TMP_FILE\" 2&gt;/dev/null\n</code></pre> <p>Files are copied from the <code>/app</code> directory - for images built via buildpacks - or <code>WORKDIR</code> - for images built via Dockerfile.</p>"},{"location":"development/plugin-creation/#avoid-calling-the-dokku-binary-directly","title":"Avoid calling the <code>dokku</code> binary directly","text":"<p>New</p> <p>Introduced in 0.6.0</p> <p>Plugins should not call the <code>dokku</code> binary directly from within plugins because clients using the <code>--app</code> argument are potentially broken when doing so.</p> <p>Plugins should instead source the <code>functions</code> file for a given plugin when attempting to call Dokku internal functions. In cases where plugin functions cannot be sourced (eg if a plugin is implemented in Golang), then call the relevant plugin triggers instead.</p>"},{"location":"development/plugin-creation/#sample-plugin","title":"Sample plugin","text":"<p>The below plugin is a dummy <code>dokku hello</code> plugin.</p> <p>Each plugin requires a <code>plugin.toml</code> descriptor file with the following required fields:</p> <pre><code>[plugin]\ndescription = \"dokku hello plugin\"\nversion = \"0.1.0\"\n[plugin.config]\n</code></pre> <p><code>hello/subcommands/default</code></p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\ncmd-hello-default() {\n  declare desc=\"prints Hello \\$APP\"\n  declare cmd=\"hello\"\n  [[ \"$1\" == \"$cmd\" ]] &amp;&amp; shift 1\n  # Support --app/$DOKKU_APP_NAME flag\n  # Use the following lines to reorder args into \"$cmd $DOKKU_APP_NAME $@\"\"\n  [[ -n $DOKKU_APP_NAME ]] &amp;&amp; set -- $DOKKU_APP_NAME $@\n  set -- $cmd $@\n  #\n  declare APP=\"$1\"\n\n  [[ -z \"$APP\" ]] &amp;&amp; dokku_log_fail \"Please specify an app to run the command on\"\n  verify_app_name \"$APP\"\n\n  echo \"Hello $APP\"\n}\n\ncmd-hello-default \"$@\"\n</code></pre> <p><code>hello/subcommands/world</code></p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\ncmd-hello-world() {\n  declare desc=\"prints Hello world\"\n  declare cmd=\"hello:world\"\n  [[ \"$1\" == \"$cmd\" ]] &amp;&amp; shift 1\n\n  echo \"Hello world\"\n}\n\ncmd-hello-world \"$@\"\n</code></pre> <p><code>hello/commands</code></p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncase \"$1\" in\n  help | hello:help)\n    help_content_func () {\n      declare desc=\"return help_content string\"\n      cat&lt;&lt;help_content\n    hello &lt;app&gt;, Says \"Hello &lt;app&gt;\"\n    hello:world, Says \"Hello world\"\nhelp_content\n    }\n\n    if [[ $1 = \"hello:help\" ]] ; then\n        echo -e 'Usage: dokku hello[:world] [&lt;app&gt;]'\n        echo ''\n        echo 'Say Hello World.'\n        echo ''\n        echo 'Example:'\n        echo ''\n        echo '$ dokku hello:world'\n        echo 'Hello world'\n        echo ''\n        echo 'Additional commands:'\n        help_content_func | sort | column -c2 -t -s,\n    else\n        help_content_func\n    fi\n    ;;\n\n  *)\n    exit $DOKKU_NOT_IMPLEMENTED_EXIT\n    ;;\n\nesac\n</code></pre>"},{"location":"development/plugin-triggers/","title":"Plugin triggers","text":"<p>Plugin triggers (formerly pluginhooks) are a good way to jack into existing Dokku infrastructure. You can use them to modify the output of various Dokku commands or override internal configuration.</p> <p>Plugin triggers are simply scripts that are executed by the system. You can use any language you want, so long as the script:</p> <ul> <li>Is executable</li> <li>Has the proper language requirements installed</li> </ul> <p>For instance, if you wanted to write a plugin trigger in PHP, you would need to have <code>php</code> installed and available on the CLI prior to plugin trigger invocation.</p> <p>The following is an example for the <code>nginx-hostname</code> plugin trigger. It reverses the hostname that is provided to nginx during deploys. If you created an executable file named <code>nginx-hostname</code> with the following code in your plugin trigger, it would be invoked by Dokku during the normal app deployment process:</p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; SUBDOMAIN=\"$2\"; VHOST=\"$3\"\n\nNEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`\necho \"$NEW_SUBDOMAIN.$VHOST\"\n</code></pre>"},{"location":"development/plugin-triggers/#available-plugin-triggers","title":"Available plugin triggers","text":"<p>There are a number of plugin-related triggers. These can be optionally implemented by plugins and allow integration into the standard Dokku setup/teardown process.</p> <p>The following plugin triggers describe those available to a Dokku installation. As well, there is an example for each trigger that you can use as templates for your own plugin development.</p> <p>Info</p> <p>The example plugin trigger code is not guaranteed to be implemented as in within dokku, and are merely simplified examples. Please look at the Dokku source for larger, more in-depth examples.</p>"},{"location":"development/plugin-triggers/#app-create","title":"<code>app-create</code>","text":"<ul> <li>Description: Creates an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-destroy","title":"<code>app-destroy</code>","text":"<ul> <li>Description: Destroys an app (with confirmation if force isn't specified)</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-exists","title":"<code>app-exists</code>","text":"<ul> <li>Description: Checks if an app exists</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-list","title":"<code>app-list</code>","text":"<ul> <li>Description: Lists all apps in available to the currently logged in user. Optionally disables filtering by user if the first argument is <code>false</code>.</li> <li>Invoked by:</li> <li>Arguments: <code>$FILTER</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-json-process-deploy-parallelism","title":"<code>app-json-process-deploy-parallelism</code>","text":"<ul> <li>Description: Decides the parallelism to use when deploying a given process type. The default is 1 process entry at a type.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-json-get-content","title":"<code>app-json-get-content</code>","text":"<ul> <li>Description: Outputs the contents of the app-json file, if any</li> <li>Invoked by: Deployment checks</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-maybe-create","title":"<code>app-maybe-create</code>","text":"<ul> <li>Description: Creates an app (gated by whether this is globally enabled or not)</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-restart","title":"<code>app-restart</code>","text":"<ul> <li>Description: Triggers an app restart</li> <li>Invoked by: <code>dokku config:clear</code>, <code>dokku config:set</code>, <code>dokku config:unset</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-urls","title":"<code>app-urls</code>","text":"<ul> <li>Description: Allows you to change the urls Dokku reports for an application. Will override any auto-detected urls.</li> <li>Invoked by: <code>dokku deploy</code>, <code>dokku url</code>, and <code>dokku urls</code></li> <li>Arguments: <code>$APP $URL_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Sets the domain to `internal.tld`\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; URL_TYPE=\"$2\"\ncase \"$URL_TYPE\" in\n  url)\n    echo \"https://internal.tld/${APP}/\"\n    ;;\n  urls)\n    echo \"https://internal.tld/${APP}/\"\n    echo \"http://internal.tld/${APP}/\"\n    ;;\nesac\n</code></pre>"},{"location":"development/plugin-triggers/#builder-build","title":"<code>builder-build</code>","text":"<ul> <li>Description: Triggers the artifact build process</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-create-dokku-image","title":"<code>builder-create-dokku-image</code>","text":"<ul> <li>Description: Allows modification of the configured dokku-image</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code> <code>$DOKKU_IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-detect","title":"<code>builder-detect</code>","text":"<ul> <li>Description: Allows overriding the auto-detected <code>herokuish</code> builder in favor of a custom one. Dockerfile gets lowest builder precedence.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; SOURCECODE_WORK_DIR=\"$2\"\n\nif [[ -f \"$SOURCECODE_WORK_DIR/project.toml\" ]]; then\n  echo -n \"pack\"\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#builder-dokku-image","title":"<code>builder-dokku-image</code>","text":"<ul> <li>Description: Allows modification of the used dokku-image.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code> <code>$DOKKU_IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-get-property","title":"<code>builder-get-property</code>","text":"<ul> <li>Description: Return the value for an app's builder property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-herokuish-allowed","title":"<code>builder-herokuish-allowed</code>","text":"<ul> <li>Description: Checks if herokuish is allowed to run on non-amd64 hosts</li> <li>Invoked by: unit tests</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-image-is-cnb","title":"<code>builder-image-is-cnb</code>","text":"<ul> <li>Description: Checks if an image is cnb-based</li> <li>Invoked by: unit tests</li> <li>Arguments: <code>$APP</code> <code>$IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-image-is-herokuish","title":"<code>builder-image-is-herokuish</code>","text":"<ul> <li>Description: Checks if an image is herokuish-based</li> <li>Invoked by: unit tests</li> <li>Arguments: <code>$APP</code> <code>$IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-release","title":"<code>builder-release</code>","text":"<ul> <li>Description: Triggers the artifact release process</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#buildpack-stack-name","title":"<code>buildpack-stack-name</code>","text":"<ul> <li>Description: Retrieves the configured buildpack stack for the pack and herokuish builders</li> <li>Invoked by: builder-herokuish and builder-pack</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#caddy-template-source","title":"<code>caddy-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the caddy compose config</li> <li>Invoked by: caddy-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#certs-exists","title":"<code>certs-exists</code>","text":"<ul> <li>Description: Echos <code>true</code> if certs exists for the app, <code>false</code> otherwise</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#certs-force","title":"<code>certs-force</code>","text":"<ul> <li>Description: Echos <code>true</code> if a cert should be simulated for the app, no output otherwise</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#check-deploy","title":"<code>check-deploy</code>","text":"<ul> <li>Description: Allows you to run checks on a deploy before Dokku allows the container to handle requests.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $CONTAINER_ID $PROC_TYPE $PORT $IP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Disables deploys of containers based on whether the\n# `DOKKU_DISABLE_DEPLOY` env var is set to `true` for an app\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_AVAILABLE_PATH/config/functions\"\n\nAPP=\"$1\"; CONTAINER_ID=\"$2\"; PROC_TYPE=\"$3\"; PORT=\"$4\" ; IP=\"$5\"\n\neval \"$(config_export app $APP)\"\nDOKKU_DISABLE_DEPLOY=\"${DOKKU_DISABLE_DEPLOY:-false}\"\n\nif [[ \"$DOKKU_DISABLE_DEPLOY\" = \"true\" ]]; then\n  echo -e \"\\033[31m\\033[1mDeploys disabled, sorry.\\033[0m\"\n  exit 1\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#checks-get-property","title":"<code>checks-get-property</code>","text":"<ul> <li>Description: Return the value for an app's checks property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#commands-help-and-commands-plugin_namehelp","title":"<code>commands help</code> and <code>commands &lt;PLUGIN_NAME&gt;:help</code>","text":"<ul> <li>Description: Your plugin should implement a <code>help</code> command in your <code>commands</code> file to take advantage of this plugin trigger. <code>commands help</code> is used by <code>dokku help</code> to aggregate all plugins abbreviated <code>help</code> output. Implementing  <code>&lt;PLUGIN_NAME&gt;:help</code> in your <code>commands</code> file gives users looking for help, a more detailed output. 'commands help' must be implemented inside the <code>commands</code> plugin file. It's recommended that <code>PLUGIN_NAME:help</code> be added to the commands file to ensure consistency among community plugins and give you a new avenue to share rich help content with your user.</li> <li>Invoked by: <code>dokku help</code> and <code>commands &lt;PLUGIN_NAME&gt;:help</code></li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Outputs help for the derp plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncase \"$1\" in\n  help | hello:help)\n    help_content_func () {\n      declare desc=\"return help_content string\"\n      cat&lt;&lt;help_content\n    hello &lt;app&gt;, Says \"Hello &lt;app&gt;\"\n    hello:world, Says \"Hello world\"\nhelp_content\n    }\n\n    if [[ $1 = \"hello:help\" ]] ; then\n        echo -e 'Usage: dokku hello[:world] [&lt;app&gt;]'\n        echo ''\n        echo 'Say Hello World.'\n        echo ''\n        echo 'Example:'\n        echo ''\n        echo '$ dokku hello:world'\n        echo 'Hello world'\n        echo ''\n        echo 'Additional commands:'\n        help_content_func | sort | column -c2 -t -s,\n    else\n        help_content_func\n    fi\n    ;;\n\n  *)\n    exit $DOKKU_NOT_IMPLEMENTED_EXIT\n    ;;\n\nesac\n</code></pre>"},{"location":"development/plugin-triggers/#config-export","title":"<code>config-export</code>","text":"<ul> <li>Description: Returns the environment variables in a specified format</li> <li>Invoked by: app-json plugin</li> <li>Arguments: <code>$APP $GLOBAL $MERGED $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#config-get","title":"<code>config-get</code>","text":"<ul> <li>Description: Fetches the app config value for a key</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#config-get-global","title":"<code>config-get-global</code>","text":"<ul> <li>Description: Fetches the global config value for a key</li> <li>Invoked by:</li> <li>Arguments: <code>$KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#core-post-deploy","title":"<code>core-post-deploy</code>","text":"<p>Info</p> <p>To avoid issues with community plugins, this plugin trigger should be used only for core plugins. Please avoid using this trigger in your own plugins.</p> <ul> <li>Description: Allows running of commands after an app's processes have been scaled up, but before old containers are torn down. Dokku core currently uses this to switch traffic on nginx.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $INTERNAL_PORT $INTERNAL_IP_ADDRESS $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Notify an external service that a successful deploy has occurred.\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncurl \"http://httpstat.us/200\"\n</code></pre>"},{"location":"development/plugin-triggers/#core-post-extract","title":"<code>core-post-extract</code>","text":"<p>Info</p> <p>To avoid issues with community plugins, this plugin trigger should be used only for core plugins. Please avoid using this trigger in your own plugins.</p> <ul> <li>Description: Allows you to modify the contents of an app after it has been extracted from git but before the image source type is detected.</li> <li>Invoked by: The <code>receive-app</code> plugin trigger</li> <li>Arguments: <code>$APP</code> <code>$TMP_WORK_DIR</code> <code>$REV</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Adds a clock process to an app's Procfile\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\nTMP_WORK_DIR=\"$2\"\nREV=\"$3\" # optional, may not be sent for tar-based builds\n\npushd \"$TMP_WORK_DIR\" &gt;/dev/null\ntouch Procfile\necho \"clock: some-command\" &gt;&gt; Procfile\npopd &amp;&gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#cron-get-property","title":"<code>cron-get-property</code>","text":"<ul> <li>Description: Return the value for an app's cron property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#cron-entries","title":"<code>cron-entries</code>","text":"<ul> <li>Description: Allows injecting cron entries into the written out scheduled cron task list. Each entry is newline delimited, and individual entries come in the form <code>$SCHEDULE;$FULL_COMMAND;$ARBITRARY_DATA</code>. Individual implementations of cron writing can decide whether and how to include these cron entries. The <code>ARBITRARY_DATA</code> includes the log file path for the basic <code>docker-local</code> cron implementation.</li> <li>Invoked by:</li> <li>Arguments: <code>$DOKKU_SCHEDULER</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nDOKKU_SCHEDULER=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#cron-write","title":"<code>cron-write</code>","text":"<ul> <li>Description: Force triggers writing out cron entries</li> <li>Invoked by:</li> <li>Arguments:</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#dependencies","title":"<code>dependencies</code>","text":"<ul> <li>Description: Used to install system-level dependencies.</li> <li>Invoked by: <code>dokku plugin:install-dependencies</code></li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Installs nginx for the current plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nexport DEBIAN_FRONTEND=noninteractive\n\ncase \"$DOKKU_DISTRO\" in\n  debian|raspbian|ubuntu)\n    apt-get -qq -y --no-install-recommends install nginx\n    ;;\n  *)\n    echo \"Installation on $DOKKU_DISTRO not supported\" 1&gt;&amp;2\n    ;;\nesac\n</code></pre>"},{"location":"development/plugin-triggers/#deploy","title":"<code>deploy</code>","text":"<ul> <li>Description: Triggers a deploy for the given app. Can override the image tag to deploy, as well as specify a single process type to deploy.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP [$IMAGE_TAG] [$PROC_TYPE]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\" IMAGE_TAG=\"$2\" PROC_TYPE=\"$3\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#deployed-app-image-repo","title":"<code>deployed-app-image-repo</code>","text":"<ul> <li>Description: Used to manage the full repo of the image being deployed. Useful for deploying from an external registry where the repository name is not <code>dokku/$APP</code></li> <li>Invoked by: <code>internal function dokku_deploy_cmd() (deploy phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"\n# change the repo from dokku/APP to dokkupaas/APP\necho \"dokkupaas/$APP\"\n</code></pre>"},{"location":"development/plugin-triggers/#deployed-app-image-tag","title":"<code>deployed-app-image-tag</code>","text":"<ul> <li>Description: Used to manage the tag of the image being deployed. Useful for deploying a specific version of an image, or when deploying from an external registry</li> <li>Invoked by: <code>internal function dokku_deploy_cmd() (deploy phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# customize the tag version\necho 'not-latest'\n</code></pre>"},{"location":"development/plugin-triggers/#deployed-app-repository","title":"<code>deployed-app-repository</code>","text":"<ul> <li>Description: Used to manage the remote repository of the image being deployed.</li> <li>Invoked by: <code>internal function dokku_deploy_cmd() (deploy phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\necho 'derp.dkr.ecr.us-east-1.amazonaws.com'\n</code></pre>"},{"location":"development/plugin-triggers/#deploy-source-set","title":"<code>deploy-source-set</code>","text":"<ul> <li>Description: Used to set metadata about how the app is being deployed</li> <li>Invoked by: <code>git:from-archive</code>, <code>git:from-image</code>, <code>git:load-image</code>, <code>git:sync</code>, and all git push commands</li> <li>Arguments: <code>$APP $SOURCE_TYPE $METADATA</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-build","title":"<code>docker-args-build</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>docker-args-process-build</code> instead</p> <ul> <li>Description:</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Sets a docker build-arg called CACHEBUST which can be used\n# to bust cache at any arbitrary point in a Dockerfile build\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nSTDIN=$(cat)\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$2\"\noutput=\"\"\n\nif [[ \"$IMAGE_SOURCE_TYPE\" == \"dockerfile\" ]]; then\n  output=\" --build-arg CACHEBUST=$(date +%s)\"\nfi\necho -n \"$STDIN$output\"\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-deploy","title":"<code>docker-args-deploy</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>docker-args-process-deploy</code> instead</p> <ul> <li>Description:</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG [$PROC_TYPE $CONTAINER_INDEX]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-process-build","title":"<code>docker-args-process-build</code>","text":"<ul> <li>Description: <code>$PROC_TYPE</code> may be set to magic <code>_all_</code> process type to signify global docker deploy options.</li> <li>Invoked by: <code>dokku ps:rebuild</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-process-deploy","title":"<code>docker-args-process-deploy</code>","text":"<ul> <li>Description: <code>$PROC_TYPE</code> may be set to magic <code>_all_</code> process type to signify global docker deploy options.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE $IMAGE_TAG [$PROC_TYPE $CONTAINER_INDEX]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; $IMAGE_SOURCE_TYPE=\"$2\" IMAGE_TAG=\"$3\"; PROC_TYPE=\"$4\"; CONTAINER_INDEX=\"$5\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-process-run","title":"<code>docker-args-process-run</code>","text":"<ul> <li>Description: <code>$PROC_TYPE</code> may be set to magic <code>_all_</code> process type to signify global docker run options.</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$3\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-run","title":"<code>docker-args-run</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>docker-args-process-run</code> instead</p> <ul> <li>Description:</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-add","title":"<code>domains-add</code>","text":"<ul> <li>Description: Adds a domain to an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$DOMAIN</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-disable","title":"<code>domains-disable</code>","text":"<ul> <li>Description: Disables domains for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$RESTART_APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-enable","title":"<code>domains-enable</code>","text":"<ul> <li>Description: Enables domains for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$RESTART_APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-list","title":"<code>domains-list</code>","text":"<ul> <li>Description: Lists all domains for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-urls","title":"<code>domains-urls</code>","text":"<ul> <li>Description: Gets an app's url(s)</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $URL_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-vhost-enabled","title":"<code>domains-vhost-enabled</code>","text":"<ul> <li>Description: Checks if a virtual hosts are enabled for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-deploy-branch","title":"<code>git-deploy-branch</code>","text":"<ul> <li>Description: Outputs the deploy branch for an app, inherited or not</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-get-property","title":"<code>git-get-property</code>","text":"<ul> <li>Description: Return the value for an app's git property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-from-archive","title":"<code>git-from-archive</code>","text":"<ul> <li>Description: Updates an app's git repository from an archive and then triggers a build</li> <li>Invoked by: <code>git:from-archive</code></li> <li>Arguments: <code>$APP $ARCHIVE_URL $ARCHIVE_TYPE $USER_NAME $USER_EMAIL</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-from-directory","title":"<code>git-from-directory</code>","text":"<ul> <li>Description: Updates an app's git repository from a source directory and then triggers a build</li> <li>Invoked by: <code>git:from-image</code> and <code>git:from-archive</code></li> <li>Arguments: <code>$APP $SOURCECODE_WORK_DIR $USER_NAME $USER_EMAIL</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-from-image","title":"<code>git-from-image</code>","text":"<ul> <li>Description: Updates an app's git repository from a docker image and then triggers a build as necessary</li> <li>Invoked by: <code>git:from-image</code></li> <li>Arguments: <code>$APP $DOCKER_IMAGE $BUILD_DIR $USER_NAME $USER_EMAIL</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-has-code","title":"<code>git-has-code</code>","text":"<ul> <li>Description: Checks to see if there is code at the specified branch</li> <li>Arguments: <code>$APP $BRANCH_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-post-pull","title":"<code>git-post-pull</code>","text":"<ul> <li>Description:</li> <li>Invoked by: <code>dokku git-upload-pack</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-pre-pull","title":"<code>git-pre-pull</code>","text":"<ul> <li>Description:</li> <li>Invoked by: <code>dokku git-upload-pack</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre> <p>Warning</p> <p>The <code>git-pre-pull</code> trigger should not be used for authentication since it does not get called for commands that use <code>git-upload-archive</code> such as <code>git archive</code>. Instead, use the <code>user-auth</code> trigger.</p>"},{"location":"development/plugin-triggers/#git-revision","title":"<code>git-revision</code>","text":"<ul> <li>Description: Allows you to fetch the current git revision for a given application</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#install","title":"<code>install</code>","text":"<ul> <li>Description: Used to setup any files/configuration for a plugin.</li> <li>Invoked by: <code>dokku plugin:install</code>.</li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Sets the hostname of the Dokku server\n# based on the output of `hostname -f`\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nif [[ ! -f  \"$DOKKU_ROOT/VHOST\" ]]; then\n  hostname -f &gt; $DOKKU_ROOT/VHOST\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#haproxy-template-source","title":"<code>haproxy-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the haproxy compose config</li> <li>Invoked by: haproxy-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#logs-get-property","title":"<code>logs-get-property</code>","text":"<ul> <li>Description: Return the value for an app's log property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-build-config","title":"<code>network-build-config</code>","text":"<ul> <li>Description: Rebuilds network configuration</li> <li>Invoked by: <code>internally triggered by proxy-build-config within proxy implementations</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-clear-config","title":"<code>network-clear-config</code>","text":"<ul> <li>Description: Clears network configuration</li> <li>Invoked by: <code>internally triggered within proxy implementations</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-config-exists","title":"<code>network-config-exists</code>","text":"<ul> <li>Description: Returns whether the network configuration for a given app exists</li> <li>Invoked by: <code>internally triggered by core-post-deploy within proxy implementations</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-ipaddr","title":"<code>network-get-ipaddr</code>","text":"<ul> <li>Description: Return the ipaddr for a given app container</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROC_TYPE $CONTAINER_ID</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-listeners","title":"<code>network-get-listeners</code>","text":"<ul> <li>Description: Return the listeners (host:port combinations) for a given app container</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-property","title":"<code>network-get-property</code>","text":"<ul> <li>Description: Return the value for an app's network property</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-static-listeners","title":"<code>network-get-static-listeners</code>","text":"<ul> <li>Description: Return the network value for an app's property</li> <li>Invoked by: <code>internally triggered by proxy-build-config</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-write-ipaddr","title":"<code>network-write-ipaddr</code>","text":"<ul> <li>Description: Write the ipaddr for a given app index</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROC_TYPE $CONTAINER_INDEX $IP_ADDRESS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-write-port","title":"<code>network-write-port</code>","text":"<ul> <li>Description: Write the port for a given app index</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROC_TYPE $CONTAINER_INDEX $PORT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#nginx-app-template-source","title":"<code>nginx-app-template-source</code>","text":"<ul> <li>Description: Return the path to a <code>sigil</code> template that should be used to generate a given nginx configuration file.</li> <li>Invoked by: <code>nginx-vhosts#build-config</code></li> <li>Arguments: <code>$APP $TEMPLATE_TYPE</code><ul> <li>The <code>TEMPLATE_TYPE</code> argument can be one of: <code>[app-config, hsts-config, validate-config]</code></li> </ul> </li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\"\nTEMPLATE_TYPE=\"$2\"\ncase \"$TEMPLATE_TYPE\" in\n  app-config)\n    echo \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/app.conf.sigil\";;\n  hsts-config)\n    echo \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/hsts.conf.sigil\";;\n  validate-config)\n    echo \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/validate.conf.sigil\";;\n  *)\n    dokku_log_fail \"Invalid template type: ${TEMPLATE_TYPE}\"\nesac\n</code></pre> <p>The default templates are viewable here: plugins/nginx-vhosts/templates/</p>"},{"location":"development/plugin-triggers/#nginx-dokku-template-source","title":"<code>nginx-dokku-template-source</code>","text":"<ul> <li>Description: Return the path to a <code>sigil</code> template that should be used to generate the <code>dokku.conf</code> nginx configuration file.</li> <li>Invoked by: <code>nginx-vhosts#install</code></li> <li>Arguments: None, however the <code>sigil</code> template can make use of the following variables: <code>$.DOKKU_ROOT $.NGINX_ROOT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\necho \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/dokku.conf.sigil\"\n</code></pre> <p>The default template is viewable here: plugins/nginx-vhosts/templates/dokku.conf.sigil</p>"},{"location":"development/plugin-triggers/#nginx-hostname","title":"<code>nginx-hostname</code>","text":"<ul> <li>Description: Allows you to customize the hostname for a given app</li> <li>Invoked by: <code>dokku domains:setup</code></li> <li>Arguments: <code>$APP $SUBDOMAIN $VHOST</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Reverses the hostname for the app\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; SUBDOMAIN=\"$2\"; VHOST=\"$3\"\n\nNEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`\necho \"$NEW_SUBDOMAIN.$VHOST\"\n</code></pre>"},{"location":"development/plugin-triggers/#nginx-pre-reload","title":"<code>nginx-pre-reload</code>","text":"<p>Warning</p> <p>The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run <code>plugn trigger network-get-listeners APP</code> within any implementation of <code>nginx-pre-reload</code> in order to retrieve all application listeners.</p> <ul> <li>Description: Run before nginx reloads hosts</li> <li>Invoked by: <code>dokku proxy:build-config</code></li> <li>Arguments: <code>$APP $INTERNAL_PORT $INTERNAL_IP_ADDRESS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs a check against all nginx conf files\n# to ensure they are valid\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nnginx -t\n</code></pre>"},{"location":"development/plugin-triggers/#openresty-template-source","title":"<code>openresty-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the openresty compose config</li> <li>Invoked by: openresty-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-clear","title":"<code>ports-clear</code>","text":"<ul> <li>Description: Clears the ports for a given app without triggering further restarts or rebuilds</li> <li>Invoked by: internally</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-configure","title":"<code>ports-configure</code>","text":"<ul> <li>Description: Configures the initial proxy ports</li> <li>Invoked by: <code>internally triggered by proxy plugins</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-get","title":"<code>ports-get</code>","text":"<ul> <li>Description: Returns a list of port mappings, newline delimited</li> <li>Invoked by: Various networking plugins</li> <li>Arguments: <code>$APP $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-get-available","title":"<code>ports-get-available</code>","text":"<ul> <li>Description: Prints out an available port greater than 1024</li> <li>Invoked by: Various networking plugins</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-get-property","title":"<code>ports-get-property</code>","text":"<ul> <li>Description: Return the value for an app's ports property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-set-detected","title":"<code>ports-set-detected</code>","text":"<ul> <li>Description: Allows builders to specify detected port mappings for a given app</li> <li>Invoked by: Builder plugins</li> <li>Arguments: <code>$APP [$PORT_MAPPING...]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-clone","title":"<code>post-app-clone</code>","text":"<ul> <li>Description: Allows you to run commands after an app was cloned.</li> <li>Invoked by: <code>dokku apps:clone</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-clone-setup","title":"<code>post-app-clone-setup</code>","text":"<ul> <li>Description: Allows you to run commands after an app is setup, and before it is rebuild. This is useful for cleaning up tasks, or ensuring configuration from an old app is copied to the new app</li> <li>Invoked by: <code>dokku apps:clone</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-rename","title":"<code>post-app-rename</code>","text":"<ul> <li>Description: Allows you to run commands after an app was renamed.</li> <li>Invoked by: <code>dokku apps:rename</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-rename-setup","title":"<code>post-app-rename-setup</code>","text":"<ul> <li>Description: Allows you to run commands after an app is setup, and before it is rebuild. This is useful for cleaning up tasks, or ensuring configuration from an old app is copied to the new app</li> <li>Invoked by: <code>dokku apps:rename</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build","title":"<code>post-build</code>","text":"<ul> <li>Description: Allows you to run commands after the build image is create for a given app.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$BUILDER_TYPE $APP $SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-buildpack","title":"<code>post-build-buildpack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using buildpacks.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-dockerfile","title":"<code>post-build-dockerfile</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using a dockerfile.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-lambda","title":"<code>post-build-lambda</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using lambda.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-pack","title":"<code>post-build-pack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using pack.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-certs-remove","title":"<code>post-certs-remove</code>","text":"<ul> <li>Description: Allows you to run commands after a cert is removed</li> <li>Invoked by: <code>dokku certs:remove</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-certs-update","title":"<code>post-certs-update</code>","text":"<ul> <li>Description: Allows you to run commands after a cert is added/updated</li> <li>Invoked by: <code>dokku certs:add</code>, <code>dokku certs:update</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-config-update","title":"<code>post-config-update</code>","text":"<ul> <li>Description: Allows you to get notified when one or more configs is added or removed. Action can be <code>set</code> or <code>unset</code>.</li> <li>Invoked by: <code>dokku config:set</code>, <code>dokku config:unset</code></li> <li>Arguments: <code>$APP</code> <code>set|unset</code> <code>key1=VALUE1 key2=VALUE2</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-container-create","title":"<code>post-container-create</code>","text":"<ul> <li>Description: This trigger should be used to do stuff to containers after they are created but before they are started. They are explicitely for commands that may involve network traffic, and not for commands that are self-contained, such as chown or tar.</li> <li>Invoked by: <code>dokku run</code>, <code>dokku ps:rebuild</code>, <code>dokku deploy</code></li> <li>Arguments: \"app|service\" \"$CONTAINER_ID\" \"$APP|$SERVICE\" \"$PHASE\"</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-create","title":"<code>post-create</code>","text":"<ul> <li>Description: Can be used to run commands after an app is created.</li> <li>Invoked by: <code>dokku apps:create</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs a command to ensure that an app\n# has a postgres database when it is starting\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\nPOSTGRES=\"$1\"\n\ndokku postgres:create $POSTGRES\ndokku postgres:link $POSTGRES $APP\n</code></pre>"},{"location":"development/plugin-triggers/#post-delete","title":"<code>post-delete</code>","text":"<ul> <li>Description: Can be used to run commands after an app is deleted.</li> <li>Invoked by: <code>dokku apps:destroy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs a command to ensure that an app's\n# postgres installation is removed\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\n\ndokku postgres:destroy $APP\n</code></pre>"},{"location":"development/plugin-triggers/#post-deploy","title":"<code>post-deploy</code>","text":"<p>Info</p> <p>Please see core-post-deploy if contributing a core plugin with the <code>post-deploy</code> hook.</p> <ul> <li>Description: Allows running of commands after an app's processes have been scaled up, but before old containers are torn down. Dokku calls this after <code>core-post-deploy</code>. Deployment Tasks are also invoked by this plugin trigger.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $INTERNAL_PORT $INTERNAL_IP_ADDRESS $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Notify an external service that a successful deploy has occurred.\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncurl \"http://httpstat.us/200\"\n</code></pre>"},{"location":"development/plugin-triggers/#post-domains-update","title":"<code>post-domains-update</code>","text":"<ul> <li>Description: Allows you to run commands once the domain for an app has been updated. It also sends in the command that has been used. This can be \"add\", \"clear\" or \"remove\". The third argument will be the optional list of domains</li> <li>Invoked by: <code>dokku domains:add</code>, <code>dokku domains:clear</code>, <code>dokku domains:remove</code>, <code>dokku domains:set</code></li> <li>Arguments: <code>$APP</code> <code>action name</code> <code>domains</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Reloads haproxy for our imaginary haproxy plugin\n# that replaces the nginx-vhosts plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nsudo service haproxy reload\n</code></pre>"},{"location":"development/plugin-triggers/#post-extract","title":"<code>post-extract</code>","text":"<ul> <li>Description: Allows you to modify the contents of an app after it has been extracted from git but before the image source type is detected.</li> <li>Invoked by: The <code>receive-app</code> plugin trigger</li> <li>Arguments: <code>$APP</code> <code>$TMP_WORK_DIR</code> <code>$REV</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Adds a clock process to an app's Procfile\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\nTMP_WORK_DIR=\"$2\"\nREV=\"$3\" # optional, may not be sent for tar-based builds\n\npushd \"$TMP_WORK_DIR\" &gt;/dev/null\ntouch Procfile\necho \"clock: some-command\" &gt;&gt; Procfile\npopd &amp;&gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#post-proxy-ports-update","title":"<code>post-proxy-ports-update</code>","text":"<ul> <li>Description: Allows you to run commands once the port mappings for an app have been updated. It also sends the invoking command. This can be \"add\", \"clear\" or \"remove\".</li> <li>Invoked by: <code>dokku ports:add</code>, <code>dokku ports:clear</code>, <code>dokku ports:remove</code></li> <li>Arguments: <code>$APP</code> <code>action name</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Rebuilds haproxy config for our imaginary haproxy plugin\n# that replaces the nginx-vhosts plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nsource \"$PLUGIN_AVAILABLE_PATH/haproxy/functions\"\nAPP=\"$1\"\n\nhaproxy-build-config \"$APP\"\n</code></pre>"},{"location":"development/plugin-triggers/#post-registry-login","title":"<code>post-registry-login</code>","text":"<ul> <li>Description: Allows running a command after the a registry has been logged into</li> <li>Invoked by: <code>dokku registry:login</code></li> <li>Arguments: <code>$DOCKER_REGISTRY_SERVER $DOCKER_REGISTRY_USER</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\n# the DOCKER_REGISTRY_PASS env var is also set\necho \"$DOCKER_REGISTRY_PASS\"\n</code></pre>"},{"location":"development/plugin-triggers/#post-release-builder","title":"<code>post-release-builder</code>","text":"<p>Warning</p> <p>Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.</p> <ul> <li>Description: Invokes a command after the build process is complete.</li> <li>Invoked by: builder plugins</li> <li>Arguments: <code>$BUILDER_TYPE $APP $IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nBUILDER_TYPE=\"$1\"; APP=\"$2\"; IMAGE=$3\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-stack-set-todo","title":"<code>post-stack-set</code> TODO","text":"<ul> <li>Description: Allows you to run commands after changing the stack</li> <li>Invoked by: buildpacks plugin</li> <li>Arguments: <code>$APP</code> <code>$VALUE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-stop","title":"<code>post-stop</code>","text":"<ul> <li>Description: Can be used to run commands after an app is manually stopped</li> <li>Invoked by: <code>dokku ps:stop</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Marks an app as manually stopped\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\n\ndokku config:set --no-restart $APP MANUALLY_STOPPED=1\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build","title":"<code>pre-build</code>","text":"<ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$BUILDER_TYPE $APP $SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-buildpack","title":"<code>pre-build-buildpack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using buildpacks.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-dockerfile","title":"<code>pre-build-dockerfile</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using a dockerfile.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-lambda","title":"<code>pre-build-lambda</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using lambda.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-pack","title":"<code>pre-build-pack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using pack.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-delete","title":"<code>pre-delete</code>","text":"<ul> <li>Description: Can be used to run commands before an app is deleted.</li> <li>Invoked by: <code>dokku apps:destroy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Clears out the gulp asset build cache for apps\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\"; GULP_CACHE_DIR=\"$DOKKU_ROOT/$APP/gulp\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\nif [[ -d $GULP_CACHE_DIR ]]; then\n  docker run \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" --rm -v \"$GULP_CACHE_DIR:/gulp\" \"$IMAGE\" find /gulp -depth -mindepth 1 -maxdepth 1 -exec rm -Rf {} \\; || true\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#pre-deploy","title":"<code>pre-deploy</code>","text":"<ul> <li>Description: Allows the running of code before the app's processes are scaled up and after the docker images are prepared.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs gulp in our container\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\ndokku_log_info1 \"Running gulp\"\nCID=$(docker run \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" -d $IMAGE /bin/bash -c \"cd /app &amp;&amp; gulp default\")\ntest $(docker wait $CID) -eq 0\nDOCKER_COMMIT_LABEL_ARGS=(\"--change\" \"LABEL org.label-schema.schema-version=1.0\" \"--change\" \"LABEL org.label-schema.vendor=dokku\" \"--change\" \"LABEL com.dokku.app-name=$APP\")\ndocker commit \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" $CID $IMAGE &gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#pre-disable-vhost","title":"<code>pre-disable-vhost</code>","text":"<ul> <li>Description: Allows you to run commands before the VHOST feature is disabled</li> <li>Invoked by: <code>dokku domains:disable</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-enable-vhost","title":"<code>pre-enable-vhost</code>","text":"<ul> <li>Description: Allows you to run commands before the VHOST feature is enabled</li> <li>Invoked by: <code>dokku domains:enable</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-receive-app","title":"<code>pre-receive-app</code>","text":"<ul> <li>Description: Allows you to customize the contents of an app directory before they are processed for deployment. The <code>IMAGE_SOURCE_TYPE</code> can be any of <code>[herokuish, dockerfile]</code></li> <li>Invoked by: <code>dokku git-hook</code>, <code>dokku tar-build-locked</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE $TMP_WORK_DIR $REV</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Adds a file called `dokku-is-awesome` to the repository\n# the contents will be the app name\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$2\"; TMP_WORK_DIR=\"$3\"; REV=\"$4\"\n\necho \"$APP\" &gt; \"$TMP_WORK_DIR/dokku-is-awesome\"\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-builder","title":"<code>pre-release-builder</code>","text":"<ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$BUILDER_TYPE $APP $IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nBUILDER_TYPE=\"$1\"; APP=\"$2\"; IMAGE_TAG=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-buildpack","title":"<code>pre-release-buildpack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using buildpacks.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Installs the graphicsmagick package into the container\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\ndokku_log_info1 \"Installing GraphicsMagick...\"\n\nCMD=\"cat &gt; gm &amp;&amp; \\\n  dpkg -s graphicsmagick &amp;&gt;/dev/null || \\\n  (apt-get update -qq &amp;&amp; apt-get -qq -y --no-install-recommends install graphicsmagick &amp;&amp; apt-get clean)\"\n\nCID=$(docker run $DOKKU_GLOBAL_RUN_ARGS -i -a stdin $IMAGE /bin/bash -c \"$CMD\")\ntest $(docker wait $CID) -eq 0\nDOCKER_COMMIT_LABEL_ARGS=(\"--change\" \"LABEL org.label-schema.schema-version=1.0\" \"--change\" \"LABEL org.label-schema.vendor=dokku\" \"--change\" \"LABEL com.dokku.app-name=$APP\")\ndocker commit \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" $CID $IMAGE &gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-lambda","title":"<code>pre-release-lambda</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using lambda.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-pack","title":"<code>pre-release-pack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-dockerfile","title":"<code>pre-release-dockerfile</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using a dockerfile.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-restore","title":"<code>pre-restore</code>","text":"<ul> <li>Description: Allows you to run commands before all containers are restored</li> <li>Invoked by: <code>dokku ps:restore</code></li> <li>Arguments:</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-start","title":"<code>pre-start</code>","text":"<ul> <li>Description: Can be used to run commands before an app is started</li> <li>Invoked by: <code>dokku ps:start</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Notifies an example url that an app is starting\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\n\ncurl \"https://dokku.me/starting/${APP}\" || true\n</code></pre>"},{"location":"development/plugin-triggers/#procfile-get-command","title":"<code>procfile-get-command</code>","text":"<ul> <li>Description: Fetches the command for a specific process type</li> <li>Invoked by: <code>internally</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE $PORT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#procfile-exists","title":"<code>procfile-exists</code>","text":"<ul> <li>Description: Checks if a procfile exists for the specified app</li> <li>Invoked by: <code>internally</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-build-config","title":"<code>proxy-build-config</code>","text":"<ul> <li>Description: Builds the proxy implementation configuration for a given app</li> <li>Invoked by: <code>internally triggered by ps:restore</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-clear-config","title":"<code>proxy-clear-config</code>","text":"<ul> <li>Description: Clears the proxy implementation configuration for a given app</li> <li>Invoked by: <code>internally triggered by apps:rename</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-disable","title":"<code>proxy-disable</code>","text":"<ul> <li>Description: Disables the configured proxy implementation for an app</li> <li>Invoked by: <code>internally triggered by ps:restore</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-enable","title":"<code>proxy-enable</code>","text":"<ul> <li>Description: Enables the configured proxy implementation for an app</li> <li>Invoked by: <code>internally triggered by ps:restore</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-is-enabled","title":"<code>proxy-is-enabled</code>","text":"<ul> <li>Description: Checks if there is a proxy enabled for the app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-type","title":"<code>proxy-type</code>","text":"<ul> <li>Description: Returns the proxy type for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ps-can-scale","title":"<code>ps-can-scale</code>","text":"<ul> <li>Description: Sets whether or not a user can scale an app with <code>ps:scale</code></li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ps-current-scale","title":"<code>ps-current-scale</code>","text":"<ul> <li>Description: Prints out the current scale contents (process-type=quantity) delimited by newlines.</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ps-set-scale","title":"<code>ps-set-scale</code>","text":"<ul> <li>Description: Sets the scale for an app based on a specified formation (process-type=quantity). Any unspecified process types will be left as is.</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $SKIP_DEPLOY $CLEAR_EXISTING [$PROCESS_TUPLE...]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#receive-app","title":"<code>receive-app</code>","text":"<ul> <li>Description: Allows you to customize what occurs when an app is received. Normally just triggers an app build.</li> <li>Invoked by: <code>dokku git-hook</code>, <code>dokku ps:rebuild</code></li> <li>Arguments: <code>$APP $REV</code> (<code>$REV</code> may not be included in cases where a repository is not pushed)</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# For our imaginary mercurial plugin, triggers a rebuild\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; REV=\"$2\"\n\ndokku hg-build $APP $REV\n</code></pre>"},{"location":"development/plugin-triggers/#receive-branch","title":"<code>receive-branch</code>","text":"<ul> <li>Description: Allows you to customize what occurs when a specific branch is received. Can be used to add support for specific branch names</li> <li>Invoked by: <code>dokku git-hook</code>, <code>dokku ps:rebuild</code></li> <li>Arguments: <code>$APP $REV $REFNAME</code></li> <li>Example:</li> </ul> <pre><code>#!/bin/bash\n# Gives Dokku the ability to support multiple branches for a given service\n# Allowing you to have multiple staging environments on a per-branch basis\n\nreference_app=$1\nrefname=$3\nnewrev=$2\nAPP=${refname/*\\//}.$reference_app\n\nif [[ ! -d \"$DOKKU_ROOT/$APP\" ]]; then\n  REFERENCE_REPO=\"$DOKKU_ROOT/$reference_app\"\n  git clone --bare --shared --reference \"$REFERENCE_REPO\" \"$REFERENCE_REPO\" \"$DOKKU_ROOT/$APP\" &gt;/dev/null\nfi\nplugn trigger receive-app $APP $newrev\n</code></pre>"},{"location":"development/plugin-triggers/#release-and-deploy","title":"<code>release-and-deploy</code>","text":"<ul> <li>Description: Triggers a release of the image tag and a subsequent deploy</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#report","title":"<code>report</code>","text":"<ul> <li>Description: Allows you to report on any custom configuration in use by your application</li> <li>Invoked by: <code>dokku report</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#resource-get-property","title":"<code>resource-get-property</code>","text":"<ul> <li>Description: Fetches a given resource property value</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$PROC_TYPE</code> <code>$RESOURCE_TYPE</code> <code>$PROPERTY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROC_TYPE=\"$2\" RESOURCE_TYPE=\"$3\" PROPERTY=\"$4\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#retire-container-failed","title":"<code>retire-container-failed</code>","text":"<ul> <li>Description: Allows you to run commands if/when retiring old containers has failed</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Send an email when a container failed to retire\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; HOSTNAME=$(hostname -s)\n\nmail -s \"$APP containers on $HOSTNAME failed to retire\" ops@dokku.me\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-app-status","title":"<code>scheduler-app-status</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Fetch the status of an app</li> <li>Invoked by: <code>dokku ps:report</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-deploy","title":"<code>scheduler-deploy</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when an app is deployed</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; IMAGE_TAG=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-detect","title":"<code>scheduler-detect</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to check which scheduler is in use for an app</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-enter","title":"<code>scheduler-enter</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to enter a running container for a given app</li> <li>Invoked by: <code>dokku enter</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $@</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; ARGS=\"$@\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-inspect","title":"<code>scheduler-inspect</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run inspect commands for all containers for a given app</li> <li>Invoked by: <code>dokku ps:inspect</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-is-deployed","title":"<code>scheduler-is-deployed</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to check if the scheduler has deployed the app</li> <li>Invoked by: Various plugins</li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-logs","title":"<code>scheduler-logs</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when retrieving container logs</li> <li>Invoked by: <code>dokku logs:failed</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $PROCESS_TYPE $TAIL $PRETTY_PRINT $NUM</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; PROCESS_TYPE=\"$3\"; TAIL=\"$4\"; PRETTY_PRINT=\"$5\"; NUM=\"$6\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-logs-failed","title":"<code>scheduler-logs-failed</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when retrieving failed container logs</li> <li>Invoked by: <code>dokku logs:failed</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-pre-restore","title":"<code>scheduler-pre-restore</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run commands before an app is restored</li> <li>Invoked by: <code>dokku ps:restore</code></li> <li>Arguments: <code>$DOKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-post-delete","title":"<code>scheduler-post-delete</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when an app is deleted</li> <li>Invoked by: <code>dokku apps:destroy</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; IMAGE_TAG=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-post-deploy-process","title":"<code>scheduler-post-deploy-process</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run a command after a process has been started</li> <li>Invoked by: scheduler-docker-local</li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROCESS_TYPE=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-post-run","title":"<code>scheduler-post-run</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands after a <code>dokku run</code> invocation is called</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $CONTAINER_ID</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; CONTAINER_ID=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-register-retired","title":"<code>scheduler-register-retired</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows scheduling retiring a local container and any related images</li> <li>Invoked by: <code>internally</code></li> <li>Arguments: <code>$APP $CONTAINER_ID</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\";\nCONTAINER_ID=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-retire","title":"<code>scheduler-retire</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when containers should be force retired from the system</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run","title":"<code>scheduler-run</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when a command is executed for your app</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP ...ARGS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; ARGS=\"${@:3}\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run-list","title":"<code>scheduler-run-list</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Lists all run containers for a given app</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; FORMAT=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run-logs","title":"<code>scheduler-run-logs</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when retrieving one-off container logs</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $CONTAINER $TAIL $PRETTY_PRINT $NUM</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; CONTAINER=\"$3\"; TAIL=\"$4\"; PRETTY_PRINT=\"$5\"; NUM=\"$6\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run-stop","title":"<code>scheduler-run-stop</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows a scheduler to stop all \"run\" containers or a specified container</li> <li>Invoked by: <code>dokku run:stop</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $CONTAINER_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; CONTAINER_NAME=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-stop","title":"<code>scheduler-stop</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when a tag is destroyed</li> <li>Invoked by: <code>dokku apps:destroy, dokku ps:stop</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $REMOVE_CONTAINERS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; REMOVE_CONTAINERS=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#storage-list","title":"<code>storage-list</code>","text":"<ul> <li>Description: Returns a list of storage mounts</li> <li>Invoked by: <code>dokku storage:list</code> and <code>dokku deploy</code></li> <li>Arguments: <code>$APP $PHASE $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#traefik-template-source","title":"<code>traefik-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the traefik compose config</li> <li>Invoked by: traefik-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#uninstall","title":"<code>uninstall</code>","text":"<ul> <li>Description: Used to cleanup after itself.</li> <li>Invoked by: <code>dokku plugin:uninstall</code></li> <li>Arguments: <code>$PLUGIN</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Cleanup up extra containers created\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nPLUGIN=\"$1\"\n\n[[ \"$PLUGIN\" = \"my-plugin\" ]] &amp;&amp; docker rmi -f \"${PLUGIN_IMAGE_DEPENDENCY}\"\n</code></pre> <p>To avoid uninstalling other plugins make sure to check the plugin name like shown in the example.</p>"},{"location":"development/plugin-triggers/#update","title":"<code>update</code>","text":"<ul> <li>Description: Can be used to run plugin updates on a regular interval. You can schedule the invoker in a cron-task to ensure your system gets regular updates.</li> <li>Invoked by: <code>dokku plugin:update</code>.</li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Update the herokuish image from git source\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncd /root/dokku\nsudo BUILD_STACK=true make install\n</code></pre>"},{"location":"development/plugin-triggers/#user-auth","title":"<code>user-auth</code>","text":"<p>This is a special plugin trigger that is executed on every command run. As Dokku sometimes internally invokes the <code>dokku</code> command, special care should be taken to properly handle internal command redirects.</p> <p>Note that the trigger should exit as follows:</p> <ul> <li><code>0</code> to continue running as normal</li> <li><code>1</code> to halt execution of the command</li> </ul> <p>The <code>SSH_USER</code> is the original ssh user. If you are running remote commands, this user will typically be <code>dokku</code>, and as such should not be trusted when checking permissions. If you are connected via ssh as a different user who then invokes <code>dokku</code>, the value of this variable will be that user's name (<code>root</code>, <code>myuser</code>, etc.).</p> <p>The <code>SSH_NAME</code> is the <code>NAME</code> variable set via the <code>sshcommand acl-add</code> command. For reference, the following command can be run as the root user to specify a specific <code>NAME</code> for a given ssh key:</p> <pre><code>sshcommand acl-add dokku NAME &lt; $PATH_TO_SSH_KEY\n</code></pre> <p>Note that the <code>NAME</code> value is set at the first ssh key match. If an ssh key is set in the <code>/home/dokku/.ssh/authorized_keys</code> multiple times, the first match will decide the value.</p> <ul> <li>Description: Allows you to deny access to a Dokku command by either ssh user or associated ssh-command NAME user.</li> <li>Invoked by: <code>dokku</code></li> <li>Arguments: <code>$SSH_USER $SSH_NAME $DOKKU_COMMAND</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Allow root/admin users to do everything\n# Deny plugin access to default users\n# Allow access to all other commands\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nSSH_USER=$1\nSSH_NAME=$2\nshift 2\n[[ \"$SSH_USER\" == \"root\" ]] &amp;&amp; exit 0\n[[ \"$SSH_NAME\" == \"admin\" ]] &amp;&amp; exit 0\n[[ \"$SSH_NAME\" == \"default\" &amp;&amp; $1 == plugin:* ]] &amp;&amp; exit 1\nexit 0\n</code></pre>"},{"location":"development/plugin-triggers/#user-auth-app","title":"<code>user-auth-app</code>","text":"<p>This is a special plugin trigger that is executed when listing apps or checking if an app exists. All Dokku commands should check if an app exists at least once before interacting with them so as not to circumvent the check.</p> <p>Note that the trigger should exit <code>0</code>, and each non-empty line on stdout is captured as a valid app name.</p> <p>The <code>SSH_USER</code> is the original ssh user. If you are running remote commands, this user will typically be <code>dokku</code>, and as such should not be trusted when checking permissions. If you are connected via ssh as a different user who then invokes <code>dokku</code>, the value of this variable will be that user's name (<code>root</code>, <code>myuser</code>, etc.).</p> <p>The <code>SSH_NAME</code> is the <code>NAME</code> variable set via the <code>sshcommand acl-add</code> command. For reference, the following command can be run as the root user to specify a specific <code>NAME</code> for a given ssh key:</p> <pre><code>sshcommand acl-add dokku NAME &lt; $PATH_TO_SSH_KEY\n</code></pre> <p>Note that the <code>NAME</code> value is set at the first ssh key match. If an ssh key is set in the <code>/home/dokku/.ssh/authorized_keys</code> multiple times, the first match will decide the value.</p> <ul> <li>Description: Allows you to deny access to a Dokku app by either ssh user or associated ssh-command NAME user.</li> <li>Invoked by: <code>dokku</code></li> <li>Arguments: <code>$SSH_USER $SSH_NAME $DOKKU_COMMAND</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# hide any apps with the prefix \"admin\"\n# if the logged in user (SSH_USER) or SSH_NAME is not `root`\n\nmain() {\n  declare SSH_USER=\"$1\" SSH_NAME=\"$2\" ARGS=(\"${@:3}\")\n\n  for arg in \"${ARGS[@]}\"; do\n    if [[ \"$arg\" == admin-* ]] &amp;&amp; [[ \"$SSH_USER\" != \"root\" ]] &amp;&amp; [[ \"$SSH_NAME\" != \"root\" ]]; then\n      continue\n    fi\n\n    echo \"${arg}\"\n  done\n}\n\nmain \"$@\"\n</code></pre>"},{"location":"development/release-process/","title":"Release Process","text":"<p>Dokku is released in intervals at most three weeks apart, though may be released much quicker.</p> <p>To propose a release, the following tasks need to be performed:</p> <pre><code>export PACKAGECLOUD_TOKEN=SOME_TOKEN\n# supports major/minor/patch/betafish\ncontrib/release-dokku\n</code></pre> <p>Info</p> <p>If you are a maintainer and need the PACKAGECLOUD_TOKEN in order to make a release, please contact @josegonzalez to get this information.</p> <p>As well, the Arch Linux package description must be updated via <code>vagrant up build-arch</code> (needs to be done after the tag is pushed to GitHub, because it is based on that)</p>"},{"location":"development/release-process/#versioning","title":"Versioning","text":"<p>Dokku follows semver standards. As we are not yet at a stable release, breaking changes will require only a minor release, while all other changes only require a patch release. Once we hit stable, breaking changes will require a major release.</p> <p>At the moment, tags need not be signed, though that may change in the future.</p>"},{"location":"development/release-process/#arch-linux-packages","title":"Arch Linux Packages","text":"<p>Arch Linux packages are not really build, because all that is needed for an Arch User Repo (AUR) package is the description of how to build the package. To make this process as easy as possible there is a vagrant box called <code>build-arch</code> that updates the version of this build description (a file called <code>PKGBUILD</code>), then runs some helper scripts to fill all additional information and does test if the package could be build. Then only those changes need to be pushed to the AUR repo and an updated version of the package is ready for usage for our Arch Linux users. For detailed information see the section below.</p> <p>The workflow looks like this:</p> <pre><code># having dokku-arch in ../dokku-arch\nvagrant up build-arch\n# wait for \"==&gt; build-arch: ==&gt; Finished making: dokku 0.32.4-2 (Mon Feb 22 23:20:37 CET 2016)\"\ncd ../dokku-arch\ngit add PKGBUILD .SRCINFO\ngit commit -m 'Update to dokku 0.9.9'\ngit push aur master\n</code></pre> <p>Info</p> <p>If you are a maintainer and need access to the AUR repositories in order to make a release, please contact @morrisjobke or @josegonzalez to get this co-maintainership.</p>"},{"location":"development/release-process/#detailed-information-for-arch-linux-packages","title":"Detailed information for Arch Linux packages","text":"<p>All of the information to build the Arch Linux package is in the AUR git repository (see dokku AUR page). The release of a AUR package only consists of pushing the package information into the AUR git repo. Then users could use that information to build the package on their machines.</p> <p>To update the package clone the repository and adjust the files in the repository. Then a helper script - <code>updpkgsums</code> - to update the SHA sum could  be called (check against the original SHA sum). Another helper script - <code>mksrcinfo</code> - needs to be called to update the meta information of the package in a file called <code>.SRCINFO</code>. The next step builds the package locally for verification - <code>makepkg</code>. As last step commit your changes and push the commit.</p> <ul> <li>dependencies are defined in the <code>depends</code> attribute in <code>PKGBUILD</code></li> <li>build steps during package build time are defined in the <code>package()</code> method in <code>PKGBUILD</code></li> <li>steps that should be executed during install/update/remove time are defined in the file <code>dokku.install</code></li> <li>detailed information about all attributes in <code>PKGBUILD</code> could be found in the Arch Linux wiki</li> <li>detailed information about the AUR workflow could be found in the AUR article in the Arch Linux wiki</li> </ul> <p>That is the usual workflow:</p> <pre><code>updpkgsums # update sha sums - compare them with the original ones\nmksrcinfo # update package metadata for AUR\nmakepkg # test package builds\ngit add PKGBUILD .SRCINFO\ngit commit -m 'Update to dokku 0.9.9'\ngit push\n</code></pre>"},{"location":"development/testing/","title":"Running Tests","text":"<p>Dokku has a full test suite to assist in quick iterating development. These tests include a linter using shellcheck, functional unit tests using the Bats testing framework, and a deployment suite of example apps that use the most popular languages and frameworks.</p> <p>We maintain the Dokku test harness within the <code>tests</code> directory:</p> <ul> <li><code>tests/unit/*.bats</code>: Bats tests</li> <li><code>tests/apps/</code>: Example applications that can be used for tests</li> </ul>"},{"location":"development/testing/#continuous-integration","title":"Continuous Integration","text":"<p>All pull requests have tests run against them on GitHub Actions, a continuous integration platform that provides Docker support for Ubuntu Focal 20.04.</p> <p>If you wish to skip tests for a particular commit, e.g. documentation changes, you may add the <code>[ci skip]</code> designator to your commit message. Commits that should be tested but have the above designator will not be merged.</p> <p>While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Focal 20.04, we only provide official installation support for that platform and the latest LTS release of Ubuntu (currently 20.04).</p>"},{"location":"development/testing/#local-test-execution","title":"Local Test Execution","text":""},{"location":"development/testing/#vagrant-vm","title":"Vagrant VM","text":"<ul> <li>Setup Dokku in a Vagrant VM.</li> <li>Run the following to setup tests and execute them:</li> </ul> <pre><code>vagrant ssh\nsudo su -\ncd ~/dokku\nmake ci-dependencies setup-deploy-tests\n</code></pre> <p>After making changes to your local Dokku clone, don't forget to update the Vagrant Dokku install.</p> <pre><code># update vagrant dokku install from local git clone\nmake copyfiles\n\n# build a specific plugin\nmake go-build-plugin copyplugin PLUGIN_NAME=apps\n</code></pre>"},{"location":"development/testing/#vscode-dev-container","title":"VSCode Dev Container","text":"<ul> <li>Open Dokku in a VSCode DevContainer</li> <li>Run the following in the VSCode terminal to setup tests and execute them:</li> </ul> <pre><code>make ci-dependencies setup-deploy-tests\n</code></pre> <p>After making changes to your local Dokku clone, don't forget to update the Vagrant Dokku install.</p> <pre><code># update vagrant dokku install from local git clone\nmake copyfiles\n\n# build a specific plugin\nmake go-build-plugin copyplugin PLUGIN_NAME=apps\n</code></pre>"},{"location":"development/testing/#executing-tests","title":"Executing tests","text":"<p>Execute the entire test suite (linter, bats tests, and app deployment tests):</p> <pre><code>make test\n</code></pre> <p>Run the linter</p> <pre><code>make lint\n</code></pre> <p>Execute all bats tests</p> <pre><code>make unit-tests\n</code></pre> <p>Execute all app deployment tests</p> <pre><code>make deploy-tests\n</code></pre>"},{"location":"development/testing/#executing-app-tests","title":"Executing App Tests","text":"<p>You may run a specific app deployment tests with a target similar to:</p> <pre><code>make deploy-test-nodejs-express\n</code></pre> <p>For a full list of test make targets check out <code>tests.mk</code> in the root of the Dokku repository.</p>"},{"location":"development/testing/#executing-a-single-test-suite","title":"Executing a single test suite","text":"<p>When working on a particular plugin, it may be useful to run only a particular test suite. This can be done by specifying the test suite path:</p> <pre><code>bats tests/unit/apps_1.bats\n</code></pre> <p>It is also possible to target multiple test suites at a time.</p> <pre><code>bats tests/unit/apps_1.bats tests/unit/certs.bats\n</code></pre>"},{"location":"development/testing/#executing-a-single-test","title":"Executing a single test","text":"<p>In order to increase testing velocity, a wrapper script around Bats is available that can be used to run a single test case within a suite.</p> <p>Tests within a suite may be listed by specifying the suite as a parameter to <code>bats</code>.</p> <pre><code>bats tests/unit/apps_1.bats\n</code></pre> <p>A single test can be specified via the <code>--filter</code> argument. The tests are selected via regex match, and all matches are executed.</p> <pre><code>bats --filter list tests/unit/apps_1.bats\n</code></pre>"},{"location":"enterprise/pro/","title":"Dokku Pro","text":"<p>Dokku Pro is a commercial offering that provides a familiar Web UI for all common tasks performed by developers. End users can expect an interface that provides various complex cli commands in an intuitive, app-centric manner, quickly speeding up tasks that might otherwise be difficult for new and old users to perform. Additionally, it provides a way to perform these tasks remotely via a json api, enabling easier, audited remote management of servers. Finally, Dokku Pro provides an alternative, https-based method for deploying code which can be used in environments that lockdown ssh access to servers.</p>"},{"location":"enterprise/pro/#purchasing","title":"Purchasing","text":"<p>Dokku Pro may be purchased online by clicking the following purchase link:</p> <p>Dokku Pro Purchase Link</p> <p>Info</p> <p>Currently, the server must be able to contact the public internet to validate the license, or it will fail to start. For offline support, inquire for enterprise offline licensing.</p>"},{"location":"enterprise/pro/#installation","title":"Installation","text":"<p>Dokku Pro is shipped as Debian and RPM packages, and depends on the following files:</p> <ul> <li><code>/etc/default/dokku-pro</code>: Configures certain environment variables for usage by the dokku-pro binary</li> <li><code>/etc/dokku-pro/license.key</code>: Contains the downloaded license key</li> <li><code>/var/lib/dokku/data/pro/db</code>: Contains the local dokku-pro database</li> </ul> <p>Please refer to the purchase email for details on configuring Dokku Pro.</p>"},{"location":"enterprise/pro/#features-and-development","title":"Features and Development","text":"<p>Dokku Pro has the following functionality:</p> <ul> <li>Shipped as a single binary for ease of use</li> <li>JSON-API-compatible API with JWT authentication</li> <li>Authenticated HTTP(S) endpoints for git push functionality</li> <li>Single Page App (SPA) Web UI exposing app, datastore, and ssh key management</li> </ul> <p>While each release is fairly feature complete, individual features and documentation will expand over time. Feature development follows a monthly release cadence, with individual bug fixes released on an as needed basis.</p>"},{"location":"getting-started/advanced-installation/","title":"Advanced installation","text":""},{"location":"getting-started/advanced-installation/#installing-via-other-methods","title":"Installing via other methods","text":"<p>For various reasons, certain hosting providers may have other steps that should be preferred to the above. If hosted on any of the following popular hosts, please follow the linked to instructions:</p> <ul> <li>DigitalOcean Installation Notes</li> <li>DreamHost Cloud Installation Notes</li> <li>Microsoft Azure Installation Notes</li> </ul> <p>As well, you may wish to customize your installation in some other fashion. or experiment with Vagrant. The guides below should get you started:</p> <ul> <li>Debian Package Installation Notes</li> <li>Docker-based Installation Notes</li> <li>Vagrant Installation Notes</li> <li>Advanced Install Customization</li> <li>Automated deployment via ansible</li> </ul>"},{"location":"getting-started/advanced-installation/#installing-from-source","title":"Installing from Source","text":"<p>You can always install Dokku straight from the latest - potentially unstable - <code>master</code> branch via the following Bash command:</p> <pre><code># using a branch results in installing from source\nwget -NP . https://dokku.com/install/master/bootstrap.sh;\nsudo DOKKU_BRANCH=master bash bootstrap.sh\n</code></pre>"},{"location":"getting-started/advanced-installation/#development","title":"Development","text":"<p>If you plan on developing Dokku, the easiest way to install from your own repository is cloning the repository and calling the install script. Example:</p> <pre><code>git clone https://github.com/yourusername/dokku.git\ncd dokku\nsudo make install\n</code></pre> <p>The <code>Makefile</code> allows source URLs to be overridden to include customizations from your own repositories. The <code>DOCKER_URL</code>, <code>PLUGN_URL</code>, <code>SSHCOMMAND_URL</code> and <code>STACK_URL</code> environment variables may be set to override the defaults (see the <code>Makefile</code> for how these apply). Example:</p> <pre><code>sudo SSHCOMMAND_URL=https://raw.githubusercontent.com/yourusername/sshcommand/master/sshcommand make install\n</code></pre>"},{"location":"getting-started/advanced-installation/#bootstrap-a-server-from-your-own-repository","title":"Bootstrap a server from your own repository","text":"<p>The bootstrap script allows the Dokku repository URL to be overridden to bootstrap a host from your own clone of Dokku using the <code>DOKKU_REPO</code> environment variable. Example:</p> <pre><code>wget -NP . https://dokku.com/install/master/bootstrap.sh;\nchmod +x bootstrap.sh\nsudo DOKKU_REPO=https://github.com/yourusername/dokku.git DOKKU_BRANCH=master ./bootstrap.sh\n</code></pre>"},{"location":"getting-started/advanced-installation/#custom-herokuish-build","title":"Custom Herokuish build","text":"<p>Dokku ships with a pre-built version of version of the Herokuish component by default. If you want to build your own version you can specify that with an environment variable.</p> <pre><code>git clone https://github.com/dokku/dokku.git\ncd dokku\nsudo BUILD_STACK=true STACK_URL=https://github.com/gliderlabs/herokuish.git make install\n</code></pre>"},{"location":"getting-started/advanced-installation/#skipping-herokuish-installation","title":"Skipping Herokuish installation","text":"<p>The Herokuish package is recommended but not required if not using Heroku buildpacks for deployment. Debian-based OS users can run the bootstrap installer via <code>sudo DOKKU_NO_INSTALL_RECOMMENDS=\" --no-install-recommends \" bash bootstrap.sh</code> to skip the dependency. Please note that this will also skip installation of other recommended dependencies.</p>"},{"location":"getting-started/advanced-installation/#configuring-an-unattended-installation","title":"Configuring an unattended installation","text":"<p>Once Dokku is installed, you'll want to configure the virtualhost setup as well as the push user. If you do not, your installation will be considered incomplete and you will not be able to deploy applications.</p> <p>For Debian, unattended installation is described Debian installation guide.</p> <p>Set up a domain using your preferred vendor and a wildcard domain pointing to the host running Dokku. You can manage this global domain using the domains plugin.</p> <p>Follow the user management documentation in order to add SSH keys for users to Dokku, or to give other Unix accounts access to Dokku.</p>"},{"location":"getting-started/advanced-installation/#vms-with-less-than-1-gb-of-memory","title":"VMs with less than 1 GB of memory","text":"<p>Having less than 1 GB of system memory available for Dokku and its containers may result in unexpected errors, such as <code>! [remote rejected] master -&gt; master (pre-receive hook declined)</code> during installation of NPM dependencies.</p> <p>To work around this issue, it might suffice to augment the Linux swap file size to a maximum of twice the physical memory size.</p> <p>To resize the swap file of a 512 MB machine to 1 GB, follow these steps while in SSH within your machine:</p> <pre><code>cd /var\ntouch swap.img\nchmod 600 swap.img\n\ndd if=/dev/zero of=/var/swap.img bs=1024k count=1000\nmkswap /var/swap.img\nswapon /var/swap.img\nfree\n\necho \"/var/swap.img    none    swap    sw    0    0\" &gt;&gt; /etc/fstab\n</code></pre> <p>Reference</p>"},{"location":"getting-started/troubleshooting/","title":"Troubleshooting","text":"<p>New</p> <p>Introduced in 0.17.0</p> <pre><code>trace:on                                       # Enables trace mode\ntrace:off                                      # Disables trace mode\n</code></pre>"},{"location":"getting-started/troubleshooting/#trace-mode","title":"Trace Mode","text":"<p>By default, Dokku will constrain the amount of output displayed for any given command run. The verbosity of output can be increased by enabling trace mode. Trace mode will turn on the <code>set -x</code> flag for bash plugins, while other plugins are free to respect the environment variable <code>DOKKU_TRACE</code> and log differently as approprate. Trace mode can be useful to see where plugins are running commands that would otherwise be unexpected.</p> <p>To enable trace mode, run <code>trace:on</code></p> ShellOutput <pre><code>dokku trace:on\n</code></pre> <pre><code>-----&gt; Enabling trace mode\n</code></pre> <p>Trace mode can be disabled with <code>trace:off</code></p> ShellOutput <pre><code>dokku trace:off\n</code></pre> <pre><code>-----&gt; Disabling trace mode\n</code></pre>"},{"location":"getting-started/troubleshooting/#common-problems","title":"Common Problems","text":""},{"location":"getting-started/troubleshooting/#i-deployed-my-app-but-i-am-getting-the-default-nginx-page","title":"I deployed my app but I am getting the default nginx page","text":"<p>Most of the time it's caused by some defaults newer versions of nginx set. To make sure that's the issue you're having run the following:</p> <pre><code>nginx -t\n## nginx: [emerg] could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32\n</code></pre> <p>If you get a similar error just edit <code>/etc/nginx/nginx.conf</code> and add the following line to your <code>http</code> section:</p> <pre><code>http {\n    (... existing content ...)\n    server_names_hash_bucket_size 64;\n    (...)\n}\n</code></pre> <p>Note that the <code>server_names_hash_bucket_size</code> setting defines the maximum domain name length. A value of 64 would allow domains with up to 64 characters. Set it to 128 if you need longer ones.</p> <p>Save the file and try stopping nginx and starting it again:</p> <pre><code>dokku nginx:stop\ndokku nginx:start\n</code></pre> <p>Using the <code>EXPOSE</code> directive in a Dockerfile may be another reason why you might see the default site. When the <code>EXPOSE</code> directive is in use and a proxy plugin is enabled (the default), the proxy plugin will listen to requests on the ports specified in the <code>EXPOSE</code> stanza.</p> <p>For example, if you have an <code>EXPOSE</code> directive like so:</p> <pre><code>EXPOSE 8000\n</code></pre> <p>The port mapping will be <code>http:8000:8000</code>.</p> <p>To avoid this issue, either of the following can be done:</p> <ul> <li>Remove <code>EXPOSE</code> directive: This will require respecting the <code>$PORT</code> environment variable (automatically set by Dokku). Once that change is deployed, the port mapping should be cleared via the <code>dokku ports:clear $APP</code> command (where <code>$APP</code> is your app name).</li> <li>Update the port mapping: Updating the port mapping to redirect port <code>80</code> to your app's exposed port via <code>dokku ports:set $APP http:80:$EXPOSED_PORT</code> can also fix the issue. This will also allow certificate management and the letsencrypt plugin to work correctly.</li> </ul> <p>See the port management documentation for more information on how Dokku exposes ports for applications and how you can configure these for your app.</p>"},{"location":"getting-started/troubleshooting/#i-want-to-deploy-my-app-but-while-pushing-i-get-the-following-error","title":"I want to deploy my app, but while pushing I get the following error","text":"<p>The following error may be emitted from a deploy:</p> <pre><code>! [remote rejected] master -&gt; master (pre-receive hook declined)\n</code></pre> <p>The <code>remote rejected</code> error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a gist containing the full log, and create an issue.</p> <p>One the reasons why you may get this error is because the command that is run in the container exited (without errors). For example, (in Procfile) when you define a new worker container to run Delayed Job and use the bin/delayed_job start command. This command deamonizes the process and exists. The container thinks it's done so it closes itself. The error you get is the one above. To fix the above problem for Delayed Job, you must define the worker to user rake jobs:work, which doesn't deamonize the process.</p>"},{"location":"getting-started/troubleshooting/#i-get-the-aforementioned-error-in-the-build-phase-after-turning-on-dokku-tracing","title":"I get the aforementioned error in the build phase (after turning on Dokku tracing)","text":"<p>Most errors that happen in this phase are due to transient network issues (either locally or remotely) buildpack bugs.</p> <p>Find the failed phase's container image (<code>077581956a92</code> in this example).</p> <pre><code>docker ps -a  | grep build\n## 94d9515e6d93        077581956a92                \"/build\"       29 minutes ago      Exited (0) 25 minutes ago                       cocky_bell\n</code></pre> <p>Start a new container with the failed image and poke around (i.e. ensure you can access the internet from within the container or attempt the failed command, if known).</p> <pre><code>docker run -ti 077581956a92 /bin/bash\ncurl -s -S icanhazip.com\n## 192.168.0.1\ncurl http://s3pository.heroku.com/node/v0.10.30/node-v0.10.30-linux-x64.tar.gz -o node-v0.10.30-linux-x64.tar.gz\ntar tzf node-v0.10.30-linux-x64.tar.gz\n## ...\n</code></pre> <p>Sometimes (especially on DigitalOcean) deploying again seems to get past these seemingly transient issues. Additionally we've seen issues if changing networks that have different DNS resolvers. In this case, you can run the following to update your <code>resolv.conf</code>.</p> <pre><code>resolvconf -u\n</code></pre> <p>Please see #841 and #649.</p>"},{"location":"getting-started/troubleshooting/#after-adding-an-ssh-key-i-am-told-i-cannot-read-from-the-remote-repository-on-push","title":"After adding an SSH key, I am told I cannot read from the remote repository on push","text":"<pre><code>Connection closed by &lt;host&gt; port 22\nfatal: Could not read from remote repository.\n\nPlease make sure you have the correct access rights\nand the repository exists.\n</code></pre> <p>Certain systems may have access to the <code>dokku</code> user via SSH disabled. Please check that the <code>dokku</code> user is allowed access to the system in the file <code>/etc/security/access.conf</code>. As Dokku does not manage this file, please consult your Operating System's documentation for more information.</p>"},{"location":"getting-started/troubleshooting/#i-want-to-deploy-my-app-but-i-am-getting-asked-for-the-password-of-the-git-user","title":"I want to deploy my app but I am getting asked for the password of the Git user","text":"<p>Sometimes the following error message may be shown on push</p> <pre><code>fatal: 'NAME' does not appear to be a git repository\nfatal: Could not read from remote repository.\n</code></pre> <p>You get asked for a password because your SSH secret key can't be found. This may happen if the private key corresponding to the public key you added with <code>sshcommand acl-add</code> is not located in the default location <code>~/.ssh/id_rsa</code>.</p> <p>You have to point SSH to the correct secret key for your domain name. Add the following to your <code>~/.ssh/config</code>:</p> <pre><code>Host DOKKU_HOSTNAME\n  IdentityFile \"~/.ssh/KEYNAME\"\n</code></pre> <p>Also see issue #116.</p>"},{"location":"getting-started/troubleshooting/#i-successfully-deployed-my-application-with-no-deployment-errors-and-receiving-bad-gateway-when-attempting-to-access-the-application","title":"I successfully deployed my application with no deployment errors and receiving Bad Gateway when attempting to access the application","text":"<p>In many cases the application will require the a <code>process.env.PORT</code> port opposed to a specified port.</p> <p>When specifying your port you may want to use something similar to:</p> <pre><code>var port = process.env.PORT || 3000\n</code></pre> <p>Please see #282.</p> <p>Additionally, your application should listen/bind to all interfaces (<code>0.0.0.0</code>). Many frameworks default to listening on <code>127.0.0.1</code>.</p> <p>Please see #5798.</p>"},{"location":"getting-started/troubleshooting/#deployment-fails-because-of-slow-internet-connection-messages-shows-gzip-stdin-unexpected-end-of-file","title":"Deployment fails because of slow internet connection, messages shows <code>gzip: stdin: unexpected end of file</code>","text":"<p>If you see output similar this when deploying:</p> <pre><code> Command: 'set -o pipefail; curl --fail --retry 3 --retry-delay 1 --connect-timeout 3 --max-time 30 https://s3-external-1.amazonaws.com/heroku-buildpack-ruby/ruby-2.0.0-p451-default-cache.tgz -s -o - | tar zxf -' failed unexpectedly:\n !\n !     gzip: stdin: unexpected end of file\n !     tar: Unexpected EOF in archive\n !     tar: Unexpected EOF in archive\n !     tar: Error is not recoverable: exiting now\n</code></pre> <p>it might that the cURL command that is supposed to fetch the buildpack (anything in the low megabyte file size range) takes too long to finish, due to slowish connection.  To overwrite the default values (connection timeout: 90 seconds, total maximum time for operation: 600 seconds), set the following environment variables:</p> <pre><code>dokku config:set --global CURL_TIMEOUT=1200\ndokku config:set --global CURL_CONNECT_TIMEOUT=180\n</code></pre> <p>Please see #509.</p> <p>Another reason for this error (although it may respond immediately ruling out a timeout issue) may be because you've set the config setting <code>SSL_CERT_FILE</code>. Using a config setting with this key interferes with the buildpack's ability to download its dependencies, so you must rename the config setting to something else, e.g. <code>MY_APP_SSL_CERT_FILE</code>.</p>"},{"location":"getting-started/troubleshooting/#build-fails-with-killed-message","title":"Build fails with <code>Killed</code> message","text":"<p>This generally occurs when the server runs out of memory. You can either add more RAM to your server or setup swap space. The follow script will create 2 GB of swap space.</p> <pre><code>sudo install -o root -g root -m 0600 /dev/null /swapfile\ndd if=/dev/zero of=/swapfile bs=1k count=2048k\nmkswap /swapfile\nswapon /swapfile\necho \"/swapfile       swap    swap    auto      0       0\" | sudo tee -a /etc/fstab\nsudo sysctl -w vm.swappiness=10\necho vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf\n</code></pre>"},{"location":"getting-started/troubleshooting/#i-successfully-deployed-my-application-with-no-deployment-errors-but-im-receiving-connection-timeout-when-attempting-to-access-the-application","title":"I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application","text":"<p>This can occur if Dokku is running on a system with a firewall like UFW enabled (some OS versions like Ubuntu have this enabled by default). You can check if this is your case by running the following script:</p> <pre><code>sudo ufw status\n</code></pre> <p>If the previous script returned <code>Status: active</code> and a list of ports, UFW is enabled and is probably the cause of the symptom described above. To disable it, run:</p> <pre><code>sudo ufw disable\n</code></pre>"},{"location":"getting-started/troubleshooting/#i-cant-connect-to-my-application-because-the-server-is-sending-an-invalid-response-or-cant-provide-a-secure-connection","title":"I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection","text":"<p>This isn't usually an issue with Dokku, but rather an app config problem. This can happen when your application is configured to enforce secure connections/HSTS, but you don't have SSL set up for the app.</p> <p>In Rails at least, if your <code>application.rb</code> or <code>environmnents/production.rb</code> include the line <code>configure.force_ssl = true</code> which includes HSTS, try commenting that out and redeploying.</p> <p>If this solves the issue temporarily, longer term you should consider configuring SSL.</p>"},{"location":"getting-started/troubleshooting/#my-application-deploys-properly-but-wont-load-in-browser-connection-refused","title":"My application deploys properly, but won't load in browser \"connection refused\"","text":"<p>This could be a result of a bad proxy configuration (<code>http:5000:5000</code> may be incorrect). Run <code>dokku ports:report node-js-app</code> to check if your app has the correct proxy configuration. It should show something like the following.</p> <pre><code>=====&gt; node-js-app ports information\n       Port map:                http:80:5000 https:443:5000\n</code></pre> <p>Set <code>dokku ports:set node-js-app http:80:5000</code> to get proxy correctly configured for http endpoint.</p>"},{"location":"getting-started/troubleshooting/#i-deployed-a-new-app-but-now-subdomains-are-miss-routed","title":"I deployed a new app but now subdomains are miss-routed","text":"<p>Sometimes nginx does something funky and cant actually reload for whatever reason.</p> <pre><code># Validate the configuration\n$ sudo nginx -t\nnginx: the configuration file /etc/nginx/nginx.conf syntax is ok\nnginx: configuration file /etc/nginx/nginx.conf test is successful\n\n$ sudo service nginx restart\n\n# Re-enable Letsencrypt\n</code></pre> <p>Example: existing AppA (https) and AppB(https), deployed NEW (non-https) then noticed right away NEW's subdomain showed AppB's content and cert but under its own subdomain (cert miss-match of course).  AppB still works.  AppA also changed to show AppB content and cert..  Other apps were unaffected.</p> <p>Consider caddy and traefik support via docker containers if this continues to be an issue.</p>"},{"location":"getting-started/uninstalling/","title":"Uninstalling","text":"<p>While we hate to see you go, if you need to uninstall Dokku, the following may help you out:</p>"},{"location":"getting-started/uninstalling/#arch-uninstallation","title":"Arch Uninstallation","text":"<pre><code># purge dokku from your system\nyay -Rsn dokku\n</code></pre>"},{"location":"getting-started/uninstalling/#debian-uninstallation","title":"Debian Uninstallation","text":"<pre><code># purge dokku from your system\napt-get purge dokku herokuish\n\n# remove any dependencies that are no longer necessary\napt-get autoremove\n</code></pre>"},{"location":"getting-started/uninstalling/#makefile-uninstallation","title":"Makefile Uninstallation","text":"<p>This is a manual deletion process, and as it is not a recommended installation method, there is currently no automated uninstallation.</p> <p>All service plugins should be unlinked from applications, stopped, and destroyed.</p> <p>All applications should be stopped, and all docker containers and images deleted:</p> <pre><code># stop all applications\ndokku ps:stop --all\n\n# cleanup containers and images\ndokku cleanup\n</code></pre> <p>The following user/group must be deleted:</p> <ul> <li>user: <code>dokku</code></li> <li>group: <code>dokku</code></li> </ul> <p>The following directories must be deleted:</p> <ul> <li><code>~dokku</code></li> <li><code>/var/lib/dokku</code></li> <li><code>/var/log/dokku</code></li> </ul>"},{"location":"getting-started/where-to-get-help/","title":"Where to Get Help","text":"<p>If you\u2019re stuck, there are a number of places you can get help:</p>"},{"location":"getting-started/where-to-get-help/#the-official-dokku-website","title":"The Official Dokku Website","text":"<ul> <li>https://dokku.com/docs/</li> </ul> <p>The Official Dokku website is always a great place to visit. It features links to oft-used developer tools, community plugins, and guides on using Dokku.</p>"},{"location":"getting-started/where-to-get-help/#monitored-locations","title":"Monitored Locations","text":"<p>The Code Of Conduct applies to all actively monitored Dokku discussion areas. Please be mindful of your neighbors on the internet.</p>"},{"location":"getting-started/where-to-get-help/#forums","title":"Forums","text":"<ul> <li>GitHub Discussions</li> </ul> <p>GitHub Discussions is a new way for the Dokku community to interact with each other! This is a place to ask questions to the community or discuss potential feature requests before filing issues.</p>"},{"location":"getting-started/where-to-get-help/#the-slack-channel","title":"The Slack Channel","text":"<ul> <li>Gliderlabs Slack (Join the <code>#dokku</code> channel)</li> </ul> <p>If you\u2019re stumped, give us a holler in the Dokku Slack channel. Someone from the development team is usually there, especially during the daylight hours for North and South American users. We\u2019d love to hear from you, whether you need some help, want to find users in your area, or would like to donate our brand new sports car.</p> <p>Chat is synced to Discord and IRC.</p>"},{"location":"getting-started/where-to-get-help/#discord","title":"Discord","text":"<ul> <li>Dokku Discord</li> </ul> <p>We provide a Dokku Discord that folks can use to ask questions or comments about the project. Someone from the development team is usually there, especially during the daylight hours for North and South American users. Feel free to join us online!</p> <p>Chat is synced to IRC and Slack.</p>"},{"location":"getting-started/where-to-get-help/#unmonitored-locations","title":"Unmonitored Locations","text":"<p>You may find help on these locations, but they are not actively monitored by the development team. The Code of Conduct still applies.</p>"},{"location":"getting-started/where-to-get-help/#stack-overflow","title":"Stack Overflow","text":"<ul> <li>The Dokku tag on Stack Overflow</li> </ul> <p>Tag your questions with <code>dokku</code> to enable existing users of Stack Overflow to find your questions.</p>"},{"location":"getting-started/where-to-get-help/#irc-on-liberachat","title":"IRC (on libera.chat)","text":"<ul> <li>irc.libera.chat/#dokku</li> </ul> <p>This location isn't as well monitored as Slack, and loses history. Chat is synced to Discord and Slack</p>"},{"location":"getting-started/install/azure/","title":"Microsoft Azure Installation Notes","text":"<ol> <li> <p>If you don't already have one generate an SSH key pair.</p> </li> <li> <p>Go to the Dokku on Azure deployment page and click Deploy to Azure.</p> </li> <li> <p>You'll be prompted to enter a few parameters, including a unique storage account name and a unique name for the subdomain used for your public IP address. For the <code>sshKeyData</code> parameter, copy and paste the contents of the public key file you just created. After a few minutes the Dokku instance will be deployed.</p> </li> <li> <p>Once the installation is complete, you should configure an ssh key and set your global domain.</p> <pre><code># usually your key is already available under the current user's `~/.ssh/authorized_keys` file\ncat ~/.ssh/authorized_keys | dokku ssh-keys:add admin\n\n# you can use any domain you already have access to\n# this domain should have an A record or CNAME pointing at your server's IP\ndokku domains:set-global dokku.me\n\n# you can also use the ip of your server\ndokku domains:set-global 10.0.0.2\n\n# finally, you can use sslip.io to get subdomain support\n# as you would with a regular domain name\n# this would be done by appending `.sslip.io` to your ip address\ndokku domains:set-global 10.0.0.2.sslip.io\n</code></pre> </li> </ol> <p>See the user management and domains documentation for more information.</p>"},{"location":"getting-started/install/debian/","title":"Debian Package Installation Notes","text":"<p>As of 0.3.18, Dokku defaults to being installed via Debian package. While certain hosts may require extra work to get running, you may optionally wish to automate the installation of Dokku without the use of our <code>bootstrap.sh</code> Bash script. The following are the steps run by said script:</p> <pre><code># install prerequisites\nsudo apt-get update -qq &gt;/dev/null\nsudo apt-get -qq -y --no-install-recommends install apt-transport-https\n\n# install docker\nwget -nv -O - https://get.docker.com/ | sh\n\n# install dokku\nwget -qO- https://packagecloud.io/dokku/dokku/gpgkey | sudo tee /etc/apt/trusted.gpg.d/dokku.asc\n# programmatically determine distro and codename\nDISTRO=\"$(awk -F= '$1==\"ID\" { print tolower($2) ;}' /etc/os-release)\"\nOS_ID=\"$(awk -F= '$1==\"VERSION_CODENAME\" { print tolower($2) ;}' /etc/os-release)\"\necho \"deb https://packagecloud.io/dokku/dokku/${DISTRO}/ ${OS_ID} main\" | sudo tee /etc/apt/sources.list.d/dokku.list\nsudo apt-get update -qq &gt;/dev/null\nsudo apt-get -qq -y install dokku\nsudo dokku plugin:install-dependencies --core\n</code></pre>"},{"location":"getting-started/install/debian/#unattended-installation","title":"Unattended installation","text":"<p>In case you want to perform an unattended installation of Dokku, this is made possible through debconf, which allows you to configure a package before installing it.</p> <p>You can set any of the below options through the <code>debconf-set-selections</code> command, for example to enable vhost-based deployments:</p> <pre><code>echo \"dokku dokku/vhost_enable boolean true\" | sudo debconf-set-selections\n</code></pre> <p>After setting the desired options, proceed with the installation as described above.</p>"},{"location":"getting-started/install/debian/#debconf-options","title":"debconf options","text":"Name Type Default Description dokku/vhost_enable boolean false Use vhost-based deployments (e.g. <code>[yourapp].dokku.me</code>) dokku/hostname string dokku.me Hostname, used as vhost domain and for showing app URL after deploy dokku/skip_key_file boolean false Don't check for the existence of the dokku/key_file. Warning: Setting this to true, will require you to manually add an SSH key later on. dokku/key_file string /root/.ssh/id_rsa.pub Path on disk to an SSH key to add to the Dokku user (Will be ignored on <code>dpkg-reconfigure</code>) dokku/nginx_enable boolean true Enable nginx-vhosts plugin"},{"location":"getting-started/install/digitalocean/","title":"DigitalOcean Droplet Installation Notes","text":"<p>DigitalOcean offers a pre-installed Dokku image. You can run this image on any sized Droplet, although larger Droplets will allow you to run larger applications.</p> <p>Info</p> <p>Please disable IPv6. There are known issues with IPv6 on DigitalOcean and Docker. If you would like to run Dokku on an IPv6 DigitalOcean Droplet, please consult this guide.</p> <ol> <li>Login to your DigitalOcean account.</li> <li>Click Create a Droplet.</li> <li>Under Choose an image &gt; Marketplace, search latest Dokku release for Ubuntu 20.04 (version numbers may vary).</li> <li>Under Choose a size, select your machine spec.</li> <li>Under Choose a datacenter region, select your region.</li> <li>Add an SSH Key.</li> <li>New Keys<ol> <li>Under Add your SSH keys click New SSH Key (this opens a dialog).</li> <li>From your terminal, execute <code>cat $HOME/.ssh/id_rsa.pub</code>.</li> <li>Copy the output and paste it into the New SSH Key dialog, provide a name and click Add SSH Key.</li> </ol> </li> <li>Existing Keys<ol> <li>Simply add a checkmark next to the existing keys you'd like to add.</li> </ol> </li> <li>Under Finalize and create, give your Droplet a hostname (not required) and click Create.</li> <li>Once created, copy the IP address to your clipboard.</li> <li>In a browser, go to the IP address you copied above and fill out the presented form to complete configuration. Failure to do so may allow others to reconfigure SSH access on your server.</li> <li>Once the web UI has been submitted, you will be redirected to our application deployment tutorial, which will guide you through deploying a sample application to your Dokku server.</li> </ol>"},{"location":"getting-started/install/docker/","title":"Docker Installation Notes","text":"<p>Pull the dokku/dokku image:</p> <pre><code>docker pull dokku/dokku:0.32.4\n</code></pre> <p>Next, run the image.</p> <pre><code>docker container run \\\n  --env DOKKU_HOSTNAME=dokku.me \\\n  --env DOKKU_HOST_ROOT=/var/lib/dokku/home/dokku \\\n  --env DOKKU_LIB_HOST_ROOT=/var/lib/dokku/var/lib/dokku \\\n  --name dokku \\\n  --publish 3022:22 \\\n  --publish 8080:80 \\\n  --publish 8443:443 \\\n  --volume /var/lib/dokku:/mnt/dokku \\\n  --volume /var/run/docker.sock:/var/run/docker.sock \\\n  dokku/dokku:0.32.4\n</code></pre> <p>The above command will start a new docker container that is ready when a message similar to <code>Runit started as PID 12345</code> appears.</p> <p>Dokku is run in the following configuration:</p> <ul> <li>The global hostname is set to <code>dokku.me</code> on boot.</li> <li>The container name is dokku.</li> <li>Container SSH port 22 is exposed on the host as 3022.</li> <li>Container HTTP port 80 is exposed on the host as 8080.</li> <li>Container HTTPS port 443 is exposed on the host as 8443.</li> <li>Data within the container is stored on the host within the <code>/var/lib/dokku</code> directory.</li> <li>Image build cache is set to the data dir + <code>/home/dokku</code>.</li> <li>The docker socket is mounted into container.</li> </ul> <p>Application repositories, plugin config, as well as plugin data are persisted to disk within the specified host directory for <code>/var/lib/dokku</code>.</p> <p>Other docker container options can also be used when running Dokku, though the specific outcome will depend upon the specified options. For example, the Dokku container's nginx port can be bound to a specific host ip by specifying <code>--publish $HOST_IP:8080:80</code>, where <code>$HOST_IP</code> is the IP desired. Please see the docker container run documentation for further explanation for various docker arguments.</p>"},{"location":"getting-started/install/docker/#plugin-installation","title":"Plugin Installation","text":""},{"location":"getting-started/install/docker/#on-dokku-start","title":"On Dokku start","text":"<p>To install custom plugins, create a <code>plugin-list</code> file in the host's <code>/var/lib/dokku</code> directory. The plugins listed herein will be automatically installed by Dokku on container boot. This file should be the following format:</p> <pre><code>plugin_name: repository_url\n</code></pre> <p>An example for installing the postgres and redis plugins follows:</p> <pre><code>postgres: https://github.com/dokku/dokku-postgres.git\nredis: https://github.com/dokku/dokku-redis.git\n</code></pre>"},{"location":"getting-started/install/docker/#prior-to-dokku-start","title":"Prior to Dokku start","text":"<p>The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any <code>plugin:install</code> command. Note that the version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.</p> <pre><code>FROM dokku/dokku:0.32.4\nRUN dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres\nRUN dokku plugin:install https://github.com/dokku/dokku-redis.git redis\n</code></pre>"},{"location":"getting-started/install/docker/#ssh-key-management","title":"SSH Key Management","text":"<p>To initialize ssh-keys within the container, use <code>docker exec</code> to enter the container and run the appropriate ssh-keys commands.</p> <pre><code>docker exec -it dokku bash\n</code></pre> <p>Please see the user management documentation for more information.</p>"},{"location":"getting-started/install/docker/#pushing-applications","title":"Pushing Applications","text":"<p>When exposing the Dokku container's SSH port (22) on 3022, something similar to the following will need to be setup within the user's <code>~/.ssh/config</code>:</p> <pre><code>Host dokku.docker\n  HostName 127.0.0.1\n  Port 3022\n</code></pre> <p>In the above example, the hostname <code>127.0.0.1</code> is being aliased to <code>dokku.docker</code>, while the port is being overriden to <code>3022</code>. All SSH commands - including git pushes - for the hostname <code>dokku.docker</code> will be transparently sent to <code>127.0.0.1:3022</code>.</p>"},{"location":"getting-started/install/dreamhost/","title":"DreamHost Cloud Server Installation Notes","text":"<p>Cloud-init script can be used to automate installation of Dokku on Dreamhost (or any other OpenStack-compatible cloud with minimal changes).</p> <p>A new server instance can be created on DreamHost Cloud from the command line using OpenStack client or from the web UI and with the same command use a cloud-init script to install Dokku. Install the OpenStack CLI, download the DreamHost Cloud credentials file before proceeding and make sure your public SSH key is added to the cloud.</p> <pre><code>source openrc.sh # Set the environment variables for DreamHost Cloud\n</code></pre> <p>This allows OpenStack client to connect to DreamHost API endpoints. The command below creates a new server instance named <code>my-dokku-instance</code> based on Ubuntu 20.04, with 2 GB RAM and 1 CPU (the flavor called <code>supersonic</code>), opening network port access to HTTP and SSH (the <code>default</code> security group), and the name of the chosen SSH key. This key will be automatically added to the new server in the <code>authorized_keys</code> for the default SSH user (<code>ubuntu</code>), and it will be reused by Dokku.</p> <pre><code>openstack server create \\\n  --image Ubuntu-20.04 \\\n  --flavor gp1.supersonic \\\n  --security-group default \\\n  --key-name $YOUR_SSH_KEYNAME \\\n  --user-data dokku-cloudinit.sh \\\n  my-dokku-instance\n</code></pre> <p>The content of dokku-cloudinit.sh script contains instructions to add Docker and Dokku's apt repositories and install Dokku with the proper debconf options set. Don't forget to add the FQDN for your application server:</p> <pre><code>#cloud-config\n\napt:\n  sources:\n    source_dokku: \n      source: 'deb https://packagecloud.io/dokku/dokku/ubuntu/ $RELEASE main'\n      key: |\n        -----BEGIN PGP PUBLIC KEY BLOCK-----\n        Version: GnuPG v1.4.11 (GNU/Linux)\n\n        mQINBFu7hksBEADJfS1wB4JJmVcJ3FYoY/F3DmEsg2/NSj/TleB7hkdFPGTaOEef\n        c6SrK6bkQas8CzCZXskg3FFUFyxJwP0yQFosJ7nQCXbuaCzkGyOaob/2D4lqniKu\n        lyFvZuN0Evh2SoJYB6Idiy3rG58/KMQxJ/73HjcrOPxwpcfIE+rfey0fo6HOcSz7\n        AS3pXMbe0VoVOt8107i9qg6PizpaPugbSOP98aq2o0sPkjvKVzPsBvXWe9lDTreI\n        X+00Z6WXjcDxmKTGvCkcJ6jk0L5r66Y6TNlJeYwFb0o7PbY7YeJSEJxw9eNozZpY\n        EYvHCzHvsv7c8s+s5MeHDvvF5qsvt5qPPfw3zwLT01g1YTQpZdSDKn72YhrQUGJM\n        j/W8ro8Ij9BYhYQMIdy+RPNQrBdKjj75kW1NLCGLlE89+6PYzlQwDFLdl9eZlUdM\n        rvxbDPM99MRBBq30xfIS6YctHr40mEqZEi6OUoImaj5bbA1H3XHVH2JsWo1ttQYo\n        5qOGGhNi7/nyI9zxVo9r97lgGLztyl6ILZt8kxnWIx1QnPmSMuUNqYfuUuKAPs1q\n        +bisBLvylnFvQSqnpEuPwUS1UDby4CzVBzshTsuykCQRiwdU9tcjzZUlKKKTRLhj\n        CZCNxv1Ovgl+3m/4R5L7YOBYGCmVW0/GvlrxPLGCjZa1O8/3nih5+cv5TwARAQAB\n        tGhodHRwczovL3BhY2thZ2VjbG91ZC5pby9kb2trdS9kb2trdSAoaHR0cHM6Ly9w\n        YWNrYWdlY2xvdWQuaW8vZG9jcyNncGdfc2lnbmluZykgPHN1cHBvcnRAcGFja2Fn\n        ZWNsb3VkLmlvPokCOAQTAQIAIgUCW7uGSwIbLwYLCQgHAwIGFQgCCQoLBBYCAwEC\n        HgECF4AACgkQ8f9oUSiLMxUN3Q/+LeoFr8p3zSp9tRcCuMXfbc7rnJ/UgJiO53jW\n        8LsXH1h5dWeh2H5VqzGjDJ3SORisAWdOMu1SWkw4mvBZQQL12iwAMZmIDmbWU73c\n        PplwGUQ4sltNxtiAVdntWC1vwSceY6/AQZwE2k60RYzg5bR2KAyZR9yGssGsekFO\n        zOuMiTswzEYoZaJla+cduAXZzGf8NZgbzhXKhyfjVodRTyNR0dhoeMwNBlH0WWzW\n        owwNOaJQ1LwDUkjrfRpkT53RJ5olRYa5ONDxuZEvmFy57bqXJh5U13m9FNWEtmF2\n        NySFltZYEL6BZQn5qehF4kqqJ0JSVsHEyEC7sU9yr93khTGjWQfcGaITZXPNyXTC\n        py/J1TeOEOz2VyvglPx/JL4dTfPg5uZCTWRXzLJDAbW26BcyFI4OyPjFly6FLj0o\n        nMUuEzdCmNpHCKWkeyXajxtYd4EMo+UHGYC7jrpsAxRib0pdHUwnOG0MeNIUtPm/\n        yW8i5St9PnX2y2qSaAoVURAI3irApn4Wc+hgRjo22l/B6ZudMAtASD5Ie8pXHNS0\n        dlsgiv3sTZachMKU+usoIgejIb0MuBhBwVJ93A4YguEqNgZg0Cz4MUpWNma6zLIN\n        Ko+3khp3z2Y/jWfNTKs41sz++png1iqjnvXjGIjKtgcFJyH+AwZzkh5LjRiahM/I\n        OO/xTaO5Ag0EW7uGSwEQAL39qC95IFVNobRvecddeL26kHPgd0JS4fjB5r01pMFR\n        3fojnEwGTLzRJVR4iTfzOiAG1XKGYmEb15NkEgEcvaLaojSsaaAHv++BqL2qXHJa\n        sfsgjKqxCAKyJps5wCEIzF1xfxHB/5BIyKenXZw9K/zlZzsfqzyehLAarZ4oMQEN\n        u/dG3TlXCf/oSBHDttLTcRTGs1I8FEaA9O0ZeV+2S/WuT0kFa6s1tRUMMWHWzMmR\n        2a+vLCE3OMWtlRk6sfhfccf4rIzjj3xyieEGKznkOycu8JOqTBRmGMl3wRS2XI7c\n        PFiV1MGRV5uhJ6a0D6DDAddL13TaXMfsZB0KkFHh8bKvAxJA9opHhl+X2NrdwsLz\n        crCWF+QdoPX494j2aWnwSOXXtW9c2b6cpDfUoGVD79IYEzL0n6dgBPwCKLcmxotF\n        Tv+H3Yy0DBn8BaQ0ZHbEgudwr73vxMgbYStGfu/bQEulcLA0vfTRGBRhzlZLE8k6\n        +fXK23R4T/3kdyJovHdnK6aIN6oFTnVM5pyLrxmUkLCaPEbnoxVtA9zOeiGhqjYT\n        pLgZMG95HgoscBlOh8BpuM2E3MSPV6XYjEKtvDpWy/i/oCPhd/PcY/qVxzj6dANU\n        gQE/8hdf6Q//SvUxZaVrVwnmWkIZshGDJj/EM8VGhKzEoZF8Xmr/aibyN3CLoSMl\n        ABEBAAGJBD4EGAECAAkFAlu7hksCGy4CKQkQ8f9oUSiLMxXBXSAEGQECAAYFAlu7\n        hksACgkQ+ytqpCHNGT+1Vg//Z0ZiIoQQCLXmbAPdA79HVLCzsvkKQ3/RlqIR7Nq1\n        JzgqPxg8drRo5+Ri+VrsIJt3AYH/lGm1UuSeycM6NrNWBpqL5FLjrMmbILQp9GMf\n        bCZLXocOwDvrfpdBuEK+AS8SuLeiZtl8DcOe9Xtv3LSxXre0hsiIZpTRIjP+qkj8\n        W7oZqUxwo1Wcnff+0snf6hPiTps/IB1utzSjxXVe86/89BWvLt/mT1o81h5mclgk\n        l1eit6BvZsO/iicLB5KbyA7DVjAnxngze0+cCUAIVbqQbZhAVw5oZbKeXedbGuxr\n        eRLWx+h5IBbtn+JwWngzueHyc3fY5b6ann06f6y6BF5+XmPRIXakYh4moJxSRQCA\n        GVKGEubH/Y1Vyq8QIX7V6PGpS39mQkoYXEztvEtyZiV3J+SyObYZVTs9d5/rhoE2\n        wXQIFTOdyHi52K2VfT3JU7rWOw5/SWuOQyyDdWgxEJuU6bUeOViOwHVkZDzwBX3Y\n        1to5cgY6dNQARplEgZZjRja4uc06u2d7Bk2CfqO4LvjV5UlPm838Ga+kGzBpp86X\n        5JBbZz9lPGf+GY7ZcROQp6ONui8P08+7EaTVtILTE0rd5g8umOnWBo1zteMv50As\n        jyIPW20kUuJMdz3V+TNag5aCMW7qnO4zwildlQZmL54+xQDuRXK8P5JlKml6gnK+\n        4SLvUA/8CALEMqxNlb06ZJc1GCU/mcQYXfkNosHaNYpORjziDnH1LBQ7AnhIhhMy\n        FwcuxpG9bABwQfoQE84Kx3zVU0xEoCGr549Kf5p7ZcqGwn3WzSql+qR/NcPRV9Dp\n        tb4iSXoTUeutR1SeVn/TI2aOWez3UyIztnam+p32e4BNuyByFRmo2e8dP1RqCg6b\n        0KwuxDDE0k3zJCpjsWROrtBVQ9Zt9rsfG5kFxJ6Qi90uJP71f8rFDUuKmxJazDf3\n        g3GHEGovUrOJO5JpvCcfCyT9mfOPxUSAKGBHj8NPY84vjqGaA9qqt54D8YT57TjR\n        5oWd8Iwex4XFHAoj59q04KmramVgP5q8VKFrxwVOhYmK6SNmvW9dEI3Y16bu9KF7\n        CJnPq/mQXEI+a/G6hZgZ8eYxOV2812WcORppezALreHJeN1HogxI972G0kalKhNC\n        p3315BKJdw/p6/j/qIob2EZOdqBsdHRKBgBVXVbaCnzgh1kKLEvJnVDio+zjEPDr\n        lR9wQbcHRbu+ZqRSEbH0of/4rx0CdCPGKSDafviKPDXnvls85tWV/lMtNxamqYvv\n        V0DUeTWQDmfiyWCgqXTiRA9U4ZFgFNWmirh38UmV7VtSlYaRos8fEQTfmN20fqTk\n        9mVAREENSiAuc4P93l8TtrN1bAqXaTX5oz+lepqWmHWvY+RiNiw=\n        =laU4\n        -----END PGP PUBLIC KEY BLOCK-----\n    source_docker: \n      source: 'deb [arch=amd64] https://download.docker.com/linux/ubuntu $RELEASE stable'\n      key: |\n        -----BEGIN PGP PUBLIC KEY BLOCK-----\n\n        mQINBFit2ioBEADhWpZ8/wvZ6hUTiXOwQHXMAlaFHcPH9hAtr4F1y2+OYdbtMuth\n        lqqwp028AqyY+PRfVMtSYMbjuQuu5byyKR01BbqYhuS3jtqQmljZ/bJvXqnmiVXh\n        38UuLa+z077PxyxQhu5BbqntTPQMfiyqEiU+BKbq2WmANUKQf+1AmZY/IruOXbnq\n        L4C1+gJ8vfmXQt99npCaxEjaNRVYfOS8QcixNzHUYnb6emjlANyEVlZzeqo7XKl7\n        UrwV5inawTSzWNvtjEjj4nJL8NsLwscpLPQUhTQ+7BbQXAwAmeHCUTQIvvWXqw0N\n        cmhh4HgeQscQHYgOJjjDVfoY5MucvglbIgCqfzAHW9jxmRL4qbMZj+b1XoePEtht\n        ku4bIQN1X5P07fNWzlgaRL5Z4POXDDZTlIQ/El58j9kp4bnWRCJW0lya+f8ocodo\n        vZZ+Doi+fy4D5ZGrL4XEcIQP/Lv5uFyf+kQtl/94VFYVJOleAv8W92KdgDkhTcTD\n        G7c0tIkVEKNUq48b3aQ64NOZQW7fVjfoKwEZdOqPE72Pa45jrZzvUFxSpdiNk2tZ\n        XYukHjlxxEgBdC/J3cMMNRE1F4NCA3ApfV1Y7/hTeOnmDuDYwr9/obA8t016Yljj\n        q5rdkywPf4JF8mXUW5eCN1vAFHxeg9ZWemhBtQmGxXnw9M+z6hWwc6ahmwARAQAB\n        tCtEb2NrZXIgUmVsZWFzZSAoQ0UgZGViKSA8ZG9ja2VyQGRvY2tlci5jb20+iQI3\n        BBMBCgAhBQJYrefAAhsvBQsJCAcDBRUKCQgLBRYCAwEAAh4BAheAAAoJEI2BgDwO\n        v82IsskP/iQZo68flDQmNvn8X5XTd6RRaUH33kXYXquT6NkHJciS7E2gTJmqvMqd\n        tI4mNYHCSEYxI5qrcYV5YqX9P6+Ko+vozo4nseUQLPH/ATQ4qL0Zok+1jkag3Lgk\n        jonyUf9bwtWxFp05HC3GMHPhhcUSexCxQLQvnFWXD2sWLKivHp2fT8QbRGeZ+d3m\n        6fqcd5Fu7pxsqm0EUDK5NL+nPIgYhN+auTrhgzhK1CShfGccM/wfRlei9Utz6p9P\n        XRKIlWnXtT4qNGZNTN0tR+NLG/6Bqd8OYBaFAUcue/w1VW6JQ2VGYZHnZu9S8LMc\n        FYBa5Ig9PxwGQOgq6RDKDbV+PqTQT5EFMeR1mrjckk4DQJjbxeMZbiNMG5kGECA8\n        g383P3elhn03WGbEEa4MNc3Z4+7c236QI3xWJfNPdUbXRaAwhy/6rTSFbzwKB0Jm\n        ebwzQfwjQY6f55MiI/RqDCyuPj3r3jyVRkK86pQKBAJwFHyqj9KaKXMZjfVnowLh\n        9svIGfNbGHpucATqREvUHuQbNnqkCx8VVhtYkhDb9fEP2xBu5VvHbR+3nfVhMut5\n        G34Ct5RS7Jt6LIfFdtcn8CaSas/l1HbiGeRgc70X/9aYx/V/CEJv0lIe8gP6uDoW\n        FPIZ7d6vH+Vro6xuWEGiuMaiznap2KhZmpkgfupyFmplh0s6knymuQINBFit2ioB\n        EADneL9S9m4vhU3blaRjVUUyJ7b/qTjcSylvCH5XUE6R2k+ckEZjfAMZPLpO+/tF\n        M2JIJMD4SifKuS3xck9KtZGCufGmcwiLQRzeHF7vJUKrLD5RTkNi23ydvWZgPjtx\n        Q+DTT1Zcn7BrQFY6FgnRoUVIxwtdw1bMY/89rsFgS5wwuMESd3Q2RYgb7EOFOpnu\n        w6da7WakWf4IhnF5nsNYGDVaIHzpiqCl+uTbf1epCjrOlIzkZ3Z3Yk5CM/TiFzPk\n        z2lLz89cpD8U+NtCsfagWWfjd2U3jDapgH+7nQnCEWpROtzaKHG6lA3pXdix5zG8\n        eRc6/0IbUSWvfjKxLLPfNeCS2pCL3IeEI5nothEEYdQH6szpLog79xB9dVnJyKJb\n        VfxXnseoYqVrRz2VVbUI5Blwm6B40E3eGVfUQWiux54DspyVMMk41Mx7QJ3iynIa\n        1N4ZAqVMAEruyXTRTxc9XW0tYhDMA/1GYvz0EmFpm8LzTHA6sFVtPm/ZlNCX6P1X\n        zJwrv7DSQKD6GGlBQUX+OeEJ8tTkkf8QTJSPUdh8P8YxDFS5EOGAvhhpMBYD42kQ\n        pqXjEC+XcycTvGI7impgv9PDY1RCC1zkBjKPa120rNhv/hkVk/YhuGoajoHyy4h7\n        ZQopdcMtpN2dgmhEegny9JCSwxfQmQ0zK0g7m6SHiKMwjwARAQABiQQ+BBgBCAAJ\n        BQJYrdoqAhsCAikJEI2BgDwOv82IwV0gBBkBCAAGBQJYrdoqAAoJEH6gqcPyc/zY\n        1WAP/2wJ+R0gE6qsce3rjaIz58PJmc8goKrir5hnElWhPgbq7cYIsW5qiFyLhkdp\n        YcMmhD9mRiPpQn6Ya2w3e3B8zfIVKipbMBnke/ytZ9M7qHmDCcjoiSmwEXN3wKYI\n        mD9VHONsl/CG1rU9Isw1jtB5g1YxuBA7M/m36XN6x2u+NtNMDB9P56yc4gfsZVES\n        KA9v+yY2/l45L8d/WUkUi0YXomn6hyBGI7JrBLq0CX37GEYP6O9rrKipfz73XfO7\n        JIGzOKZlljb/D9RX/g7nRbCn+3EtH7xnk+TK/50euEKw8SMUg147sJTcpQmv6UzZ\n        cM4JgL0HbHVCojV4C/plELwMddALOFeYQzTif6sMRPf+3DSj8frbInjChC3yOLy0\n        6br92KFom17EIj2CAcoeq7UPhi2oouYBwPxh5ytdehJkoo+sN7RIWua6P2WSmon5\n        U888cSylXC0+ADFdgLX9K2zrDVYUG1vo8CX0vzxFBaHwN6Px26fhIT1/hYUHQR1z\n        VfNDcyQmXqkOnZvvoMfz/Q0s9BhFJ/zU6AgQbIZE/hm1spsfgvtsD1frZfygXJ9f\n        irP+MSAI80xHSf91qSRZOj4Pl3ZJNbq4yYxv0b1pkMqeGdjdCYhLU+LZ4wbQmpCk\n        SVe2prlLureigXtmZfkqevRz7FrIZiu9ky8wnCAPwC7/zmS18rgP/17bOtL4/iIz\n        QhxAAoAMWVrGyJivSkjhSGx1uCojsWfsTAm11P7jsruIL61ZzMUVE2aM3Pmj5G+W\n        9AcZ58Em+1WsVnAXdUR//bMmhyr8wL/G1YO1V3JEJTRdxsSxdYa4deGBBY/Adpsw\n        24jxhOJR+lsJpqIUeb999+R8euDhRHG9eFO7DRu6weatUJ6suupoDTRWtr/4yGqe\n        dKxV3qQhNLSnaAzqW/1nA3iUB4k7kCaKZxhdhDbClf9P37qaRW467BLCVO/coL3y\n        Vm50dwdrNtKpMBh3ZpbB1uJvgi9mXtyBOMJ3v8RZeDzFiG8HdCtg9RvIt/AIFoHR\n        H3S+U79NT6i0KPzLImDfs8T7RlpyuMc4Ufs8ggyg9v3Ae6cN3eQyxcK3w0cbBwsh\n        /nQNfsA6uu+9H7NhbehBMhYnpNZyrHzCmzyXkauwRAqoCbGCNykTRwsur9gS41TQ\n        M8ssD1jFheOJf3hODnkKU+HKjvMROl1DK7zdmLdNzA1cvtZH/nCC9KPj1z8QC47S\n        xx+dTZSx4ONAhwbS/LN3PoKtn8LPjY9NP9uDWI+TWYquS2U+KHDrBDlsgozDbs/O\n        jCxcpDzNmXpWQHEtHU7649OXHP7UeNST1mCUCH5qdank0V1iejF6/CfTFU4MfcrG\n        YT90qFF93M3v01BbxP+EIY2/9tiIPbrd\n        =0YYh\n        -----END PGP PUBLIC KEY BLOCK-----\n\n  debconf_selections:\n    vhost:    dokku dokku/vhost_enable boolean true\n    # set the domain name of the new Dokku server\n    hostname: dokku dokku/hostname string $YOUR_FULL_QUALIFIED_DOMAIN\n    # this copies over the public SSH key assigned to the server\n    key:      dokku dokku/key_file string /home/ubuntu/.ssh/authorized_keys\n\npackages:\n    - dokku\npackage_update: true\npackage_upgrade: true\npackage_reboot_if_required: true\n</code></pre> <p>Shortly after running the create command you will get a confirmation that the instance has been created, and after about a minute it should be ready to login. Check the IP of the instance through the web UI or by running:</p> <pre><code>nova list\n</code></pre> <p>SSH with the <code>ubuntu</code> username and the public key previously added. Keep in mind that if you logged in quick enough Dokku might still be installing in the background, and not be ready. The installation takes a few minutes.</p>"},{"location":"getting-started/install/vagrant/","title":"Vagrant Installation Notes","text":"<ol> <li> <p>Download and install VirtualBox.</p> </li> <li> <p>Download and install Vagrant.</p> </li> <li> <p>Clone Dokku.</p> <pre><code>git clone https://github.com/dokku/dokku.git\n</code></pre> </li> <li> <p>Create VM.</p> <pre><code># Optional ENV arguments:\n# - `BOX_NAME`\n# - `BOX_URI`\n# - `BOX_MEMORY`\n# - `DOKKU_DOMAIN`\n# - `DOKKU_IP`\n# - `FORWARDED_PORT`.\ncd path/to/dokku\n\n# for most users\nvagrant up\n\n# windows users must instead use the following in an elevated command prompt\nvagrant up dokku-windows\n</code></pre> </li> <li> <p>Setup SSH Config in <code>~/.ssh/config</code>.</p> <pre><code>Host dokku.me\n    Port 22\n</code></pre> <p>For users that have customized the IP address of their VM - either in a custom <code>Vagrantfile</code> or via the <code>DOKKU_IP</code> environment variable - and are not using <code>10.0.0.2</code> for the Vagrant IP, you'll need to instead use the output of <code>vagrant ssh-config dokku</code> for your <code>~/.ssh/config</code> entry.</p> </li> <li> <p>Connect to the server via <code>vagrant ssh</code> and add your ssh key to the install. Additionally, set the global domain name to <code>dokku.me</code>.</p> <pre><code># usually your key is already available under the current user's `~/.ssh/authorized_keys` file\ncat ~/.ssh/authorized_keys | dokku ssh-keys:add admin\n\n# you can use any domain you already have access to\ndokku domains:set-global dokku.me\n</code></pre> <p>Please note, the <code>dokku.me</code> domain is setup to point to <code>10.0.0.2</code> along with all subdomains (i.e. <code>yourapp.dokku.me</code>). If you change the <code>DOKKU_IP</code> in your Vagrant setup you'll need to update your <code>/etc/hosts</code> file to point your reconfigured IP address.</p> </li> </ol> <p>You are now ready to deploy an app or install plugins.</p>"},{"location":"getting-started/installation/","title":"Getting Started with Dokku","text":""},{"location":"getting-started/installation/#what-is-dokku","title":"What is Dokku?","text":"<p>Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. Dokku supports building apps on the fly from a <code>git push</code> via either Dockerfile or by auto-detecting the language with Buildpacks, and then starts containers based on your built image. Using technologies such as nginx and cron, Web processes are automatically routed to, while background processes and automated cron tasks are also managed by Dokku.</p>"},{"location":"getting-started/installation/#system-requirements","title":"System Requirements","text":"<p>To start using Dokku, you'll need a system that meets the following minimum requirements:</p> <ul> <li>A fresh installation of any of the following operating systems:<ul> <li>Ubuntu 20.04/22.04</li> <li>Debian 10+ x64</li> </ul> </li> <li>A server with one of the following architectures<ul> <li>AMD64 (alternatively known as <code>x86_64</code>), commonly used for Intel cloud servers</li> <li>ARMV8 (alternatively known as <code>arm64</code>), commonly used for Raspberry PI and AWS Graviton</li> </ul> </li> </ul> <p>To avoid memory pressure during builds or runtime of your applications, we suggest the following:</p> <ul> <li>At least 1 GB of system memory<ul> <li>If your system has less than 1GB of memory, you can use this workaround.</li> </ul> </li> </ul> <p>Finally, we recommend attaching at least one domain name to your server. This is not required, but using a domain name will make app access easier. When connecting a domain, either a single domain or a wildcard may be associated to the server's IP.</p> <ul> <li>Wildcard domain (<code>*.domain.tld</code> A Record): will allow access to apps via <code>$APP.domain.tld</code>.</li> <li>Single domain (<code>domain.tld</code> A or CNAME Record): will result in apps being accessed via <code>domain.tld:$RANDOM_PORT</code>.</li> </ul> <p>Please see the dns documentation and domains documentation for more details.</p>"},{"location":"getting-started/installation/#installing-the-latest-stable-version","title":"Installing the latest stable version","text":"<p>This is the simple method of installing Dokku. For alternative methods of installation, see the advanced install guide.</p>"},{"location":"getting-started/installation/#1-install-dokku","title":"1. Install Dokku","text":"<p>To install the latest stable version of Dokku, you can run the following shell commands:</p> <pre><code># for debian systems, installs Dokku via apt-get\nwget -NP . https://dokku.com/install/v0.32.4/bootstrap.sh\nsudo DOKKU_TAG=v0.32.4 bash bootstrap.sh\n</code></pre> <p>The installation process takes about 5-10 minutes, depending upon internet connection speed.</p>"},{"location":"getting-started/installation/#2-setup-ssh-key-and-virtualhost-settings","title":"2. Setup SSH key and Virtualhost Settings","text":"<p>Once the installation is complete, you should configure an ssh key and set your global domain.</p> <pre><code># usually your key is already available under the current user's `~/.ssh/authorized_keys` file\ncat ~/.ssh/authorized_keys | dokku ssh-keys:add admin\n\n# you can use any domain you already have access to\n# this domain should have an A record or CNAME pointing at your server's IP\ndokku domains:set-global dokku.me\n\n# you can also use the ip of your server\ndokku domains:set-global 10.0.0.2\n\n# finally, you can use sslip.io to get subdomain support\n# as you would with a regular domain name\n# this would be done by appending `.sslip.io` to your ip address\ndokku domains:set-global 10.0.0.2.sslip.io\n</code></pre> <p>See the user management and domains documentation for more information.</p>"},{"location":"getting-started/installation/#3-deploy-your-first-application","title":"3. Deploy your first application","text":"<p>At this point, you should be able to deploy to the Dokku installation.</p>"},{"location":"getting-started/upgrading/","title":"Upgrading","text":"<p>If your version of Dokku is pre 0.3.0 (check with <code>dokku version</code>), we recommend a fresh install on a new server.</p>"},{"location":"getting-started/upgrading/#security-updates","title":"Security Updates","text":"<p>For any security related updates, please follow our Twitter account. As Dokku does not run any daemons, the security risk introduced by our software is minimal.</p> <p>Your operating system may occasionally provide security updates. We recommend setting unattended upgrades for your operating system. Here are some helpful links:</p> <ul> <li>Arch Linux System Maintenance</li> <li>Debian Unattended Upgrades</li> <li>Ubuntu Unattended Upgrades</li> </ul> <p>Docker releases updates periodically to their engine. We recommend reading their release notes and upgrading accordingly. Please see the Docker documentation for more details.</p>"},{"location":"getting-started/upgrading/#migration-guides","title":"Migration Guides","text":"<p>Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.</p> <ul> <li>Upgrading to 0.32</li> <li>Upgrading to 0.31</li> <li>Upgrading to 0.30</li> <li>Upgrading to 0.29</li> <li>Upgrading to 0.28</li> <li>Upgrading to 0.27</li> <li>Upgrading to 0.26</li> <li>Upgrading to 0.25</li> <li>Upgrading to 0.24</li> <li>Upgrading to 0.23</li> <li>Upgrading to 0.22</li> <li>Upgrading to 0.21</li> <li>Upgrading to 0.20</li> <li>Upgrading to 0.10</li> <li>Upgrading to 0.9</li> <li>Upgrading to 0.8</li> <li>Upgrading to 0.7</li> <li>Upgrading to 0.6</li> <li>Upgrading to 0.5</li> </ul>"},{"location":"getting-started/upgrading/#before-upgrading","title":"Before upgrading","text":"<p>If you'll be updating docker or the herokuish package simultaneously, it's recommended that you stop all applications before upgrading and rebuild afterwards. This is not required if the upgrade only impacts the <code>dokku</code> package.</p> <p>Why do we recommend stopping all apps?</p> <ul> <li><code>docker</code>: Containers may be randomly reset during the upgrade process, resulting in   requests being sent to the wrong containers. Acknowledging and scheduling downtime   thus becomes much more important.</li> <li><code>herokuish</code>: While not required, it may be useful to take advantage of the latest   base image. Herokuish changes do not cause issues unless the base OS changes, which   may happen in minor or major releases.</li> </ul> <pre><code># for 0.22.0 and newer versions, use\ndokku ps:stop --all\n\n# for versions between 0.11.4 and 0.21.4, use\ndokku ps:stopall\n\n# for versions between 0.8.1 and 0.11.3, use\ndokku --quiet apps:list | xargs -L1 dokku ps:stop\n\n# for versions older than 0.8.1, use\ndokku --quiet apps | xargs -L1 dokku ps:stop\n</code></pre>"},{"location":"getting-started/upgrading/#after-upgrading","title":"After upgrading","text":"<p>After upgrading, you should rebuild the applications to take advantage of any new buildpacks that were released:</p> <pre><code>dokku ps:rebuild --all\n</code></pre>"},{"location":"getting-started/upgrading/#upgrading-using-dokku-update","title":"Upgrading using <code>dokku-update</code>","text":"<p>We provide a helpful binary called <code>dokku-update</code>. This is a recommended package that:</p> <ul> <li>Can be installed separately, so upgrading Dokku will not affect the running of this package.</li> <li>Automates many of the upgrade instructions for you.</li> <li>Provides a clean way for us to further enhance the upgrade process in the future.</li> </ul> <p>This binary is available on Debian and RPM-based systems from our package repositories under the name <code>dokku-update</code>. When installing from source, this is available from a separate Github repository at dokku/dokku-update.</p>"},{"location":"getting-started/upgrading/#upgrading-using-apt","title":"Upgrading using <code>apt</code>","text":"<p>If Dokku was installed in a Debian or Ubuntu system, via <code>apt-get install dokku</code> or <code>bootstrap.sh</code>, you can upgrade with <code>apt-get</code>:</p> <pre><code># update your local apt cache\nsudo apt-get update -qq\n\n# update dokku and its dependencies\nsudo apt-get -qq -y --no-install-recommends install dokku herokuish sshcommand plugn gliderlabs-sigil dokku-update dokku-event-listener\n\n# or just upgrade every package:\nsudo apt-get upgrade\n</code></pre>"},{"location":"getting-started/upgrading/#upgrading-from-source","title":"Upgrading from source","text":"<p>If you installed Dokku from source (less common), upgrade with:</p> <pre><code>cd ~/dokku\ngit pull --tags origin master\n\n# continue to install from source\nsudo DOKKU_BRANCH=master make install\n\n# upgrade to debian package-based installation\nsudo make install\n</code></pre> <p>To upgrade Herokuish from source, upgrade with:</p> <pre><code>cd /tmp\ngit clone https://github.com/gliderlabs/herokuish.git\ncd herokuish\nCIRCLECI=true IMAGE_NAME=gliderlabs/herokuish BUILD_TAG=latest make build/docker\n</code></pre>"},{"location":"networking/dns/","title":"DNS Configuration","text":"<p>Note</p> <p>This is a work in progress.</p>"},{"location":"networking/dns/#dns-versions","title":"DNS Versions","text":"<p>There are many different DNS servers 'in the wild'.  Some of the popular ones on Linux are BIND, dnsmasq, and pdns.  Windows has its own built-in DNS server as well as Unbound, Posadis, and more.  A full list of DNS packages can be found on Wikipedia under Comparison of DNS Server Software.  In addition to the various DNS packages, there are tens of thousands of Managed DNS Providers out that all have different DNS interfaces.</p>"},{"location":"networking/dns/#focus","title":"Focus","text":"<p>Because there are so many different DNS server packages out there as well as a tremendous number of Managed DNS Providers, we will focus on the concepts of DNS as well as providing examples in the 'BIND' format so you can adapt the information to your own server package or managed DNS provider.</p>"},{"location":"networking/dns/#assumptions","title":"Assumptions","text":"<ul> <li>We assume you have a passing familiarity with DNS.  If not, you can read an in-depth article on DNS.  But basically you need to know that DNS changes names (like example.tld) into addresses (like 127.0.0.1)</li> <li>We assume you already have a domain name registered and pointed to your favorite Managed DNS Provider or have your own BIND DNS server running.</li> <li>You have a server on the internet and are about to follow the instructions in the README to get Dokku installed.  Don't do the install just yet though.</li> </ul>"},{"location":"networking/dns/#caching","title":"Caching","text":"<p>Please remember that DNS relies heavily on caching.  Changes you make to DNS could take anywhere from a few seconds to a few days to propagate.  If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes.</p>"},{"location":"networking/dns/#getting-started","title":"Getting started","text":"<p>For the examples, we will use the domain name <code>example.tld</code> and the IP address <code>127.0.0.1</code>.</p> <p>Dokku uses DNS to differentiate between apps on your dokku-powered server.  If you are using the domain <code>example.tld</code>, and you have two apps <code>node-js-app1</code> and <code>node-js-app2</code>, Dokku will make them available at <code>node-js-app1.example.tld</code> and <code>node-js-app2.example.tld</code>.</p> <p>To get started, you need to know the IP address of your Dokku server.  Connect to it and run <code>ifconfig</code> or <code>ip addr</code> to see the IP address.</p> <p>Now you have to make a decision about your domain.  Do you want everything and anything at <code>example.tld</code> to go to your Dokku server, or would you rather use a 'sub domain' for your Dokku server?</p> <p>In other words, do you want your applications on your Dokku server accessible via <code>node-js-app.example.tld</code> or via <code>node-js-app.myserver.example.tld</code>?</p>"},{"location":"networking/dns/#using-a-sub-domain-node-js-appmyserverexampletld","title":"Using a sub-domain (node-js-app.myserver.example.tld)","text":"<p>Using a sub-domain is easy.  When you set up your server, you probably gave it a name like <code>myserver.example.tld</code>.</p> <p>Go in to your Managed DNS provider and create an <code>A</code> record named <code>myserver</code> and put in the IP address you got from your server a few moments ago.</p> <p>Hopefully your managed DNS provider also supports wildcards.  Create a second <code>A</code> record named <code>*.myserver</code> along with the IP address you got from your server a few moments ago.</p> <p>If you are using BIND, your zone file will look similar to this:</p> <pre><code>$ORIGIN example.tld\n$TTL 5m\n\nmyserver         IN      A       127.0.0.1\n*.myserver       IN      A       127.0.0.1\n</code></pre> <p>You can verify your changes in Linux by trying one or more of the following commands:</p> <ul> <li><code>host myserver.example.tld</code></li> <li><code>dig -t A myserver.example.tld</code></li> <li><code>nslookup myserver.example.tld</code></li> </ul> <p>Now is a good time to remind you that the answers you get MAY BE CACHED.</p> <p>If everything is working correctly, you should also be able to query for any other name under <code>myserver.example.tld</code> and get back the IP address of your server.  Try:</p> <ul> <li><code>host test.myserver.example.tld</code></li> <li><code>host xyzzy.myserver.example.tld</code></li> </ul> <p>If they all return your IP address, you have set DNS up properly for dokku.  You should also be able to <code>ssh root@myserver.example.tld</code> and access your server.</p> <p>Proceed with the setup instructions in the installation documentation</p>"},{"location":"networking/dns/#using-the-root-of-your-domain-node-js-appexampletld","title":"Using the root of your domain (node-js-app.example.tld)","text":"<p>This section is a work in progress.  It is incomplete.</p> <p>Using the 'root' of your domain is nearly identical to the previous example.</p> <ul> <li>hostname is under <code>example.tld</code>, still needs <code>A</code> record.</li> <li>Update your global domain using the domains plugin.</li> </ul>"},{"location":"networking/network/","title":"Network Management","text":"<p>New</p> <p>Introduced in 0.11.0, Enhanced in 0.20.0</p> <pre><code>network:create &lt;network&gt;                 # Creates an attachable docker network\nnetwork:destroy &lt;network&gt;                # Destroys a docker network\nnetwork:exists &lt;network&gt;                 # Checks if a docker network exists\nnetwork:info &lt;network&gt;                   # Outputs information about a docker network\nnetwork:list                             # Lists all docker networks\nnetwork:report [&lt;app&gt;] [&lt;flag&gt;]          # Displays a network report for one or more apps\nnetwork:rebuild &lt;app&gt;                    # Rebuilds network settings for an app\nnetwork:rebuildall                       # Rebuild network settings for all apps\nnetwork:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)        # Set or clear a network property for an app\n</code></pre> <p>The Network plugin allows developers to abstract the concept of container network management, allowing developers to both change what networks a given container is attached to as well as rebuild the configuration on the fly.</p>"},{"location":"networking/network/#usage","title":"Usage","text":""},{"location":"networking/network/#listing-networks","title":"Listing networks","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>You can easily list all available networks using the <code>network:list</code> command:</p> ShellOutput <pre><code>dokku network:list\n</code></pre> <pre><code>=====&gt; Networks\nbridge\nhost\nnone\ntest-network\n</code></pre> <p>Note that you can easily hide extra output from Dokku commands by using the <code>--quiet</code> flag, which makes it easier to parse on the command line.</p> ShellOutput <pre><code>dokku --quiet network:list\n</code></pre> <pre><code>bridge\nhost\nnone\ntest-network\n</code></pre>"},{"location":"networking/network/#creating-a-network","title":"Creating a network","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>Docker networks can be created via the <code>network:create</code> command. Executing this command will create an attachable <code>bridge</code> network. This can be used to route requests between containers without going through any public network.</p> ShellOutput <pre><code>dokku network:create test-network\n</code></pre> <pre><code>-----&gt; Creating network test-network\n</code></pre> <p>Specifying other additional flags or other types of networks can be created directly via the <code>docker</code> command.</p>"},{"location":"networking/network/#destroying-a-network","title":"Destroying a network","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>A Docker network without any associated containers may be destroyed via the <code>network:destroy</code> command. Docker will refuse to destroy networks that have containers attached.</p> ShellOutput <pre><code>dokku network:destroy test-network\n</code></pre> <pre><code> !     WARNING: Potentially Destructive Action\n !     This command will destroy network test.\n !     To proceed, type \"test\"\n-----&gt; Destroying network test\n</code></pre> <p>Info</p> <p>test</p> <p>As the command is destructive, it will default to asking for confirmation before executing the removal of the network. This may be avoided by providing the <code>--force</code> flag:</p> ShellOutput <pre><code>dokku --force network:destroy test-network\n</code></pre> <pre><code>-----&gt; Destroying network test\n</code></pre>"},{"location":"networking/network/#checking-if-a-network-exists","title":"Checking if a network exists","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the <code>network:exists</code> command:</p> ShellOutput <pre><code>dokku network:exists nonexistent-network\n</code></pre> <pre><code>Network does not exist\n</code></pre> <p>The <code>network:exists</code> command will return non-zero if the network does not exist, and zero if it does.</p>"},{"location":"networking/network/#checking-network-info","title":"Checking network info","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>Network information can be retrieved via the <code>network:info</code> command. This is a slightly different version of the <code>docker network</code> command.</p> ShellOutput <pre><code>dokku network:info test-network\n</code></pre> <pre><code>// TODO\n</code></pre>"},{"location":"networking/network/#routing-an-app-to-a-known-ipport-combination","title":"Routing an app to a known ip:port combination","text":"<p>In some cases, it may be necessary to route an app to an existing <code>$IP:$PORT</code> combination. This is particularly the case for internal admin tools or services that aren't run by Dokku but have a web ui that would benefit from being exposed by Dokku. This can be done by using a proxy application and routing requests through that.</p> <pre><code># for a service listening on:\n# - ip address: 127.0.0.1\n# - port: 8080\n\n# create the app\ndokku apps:create local-app\n\n# add an extra host that maps host.docker.internal to the docker gateway\ndokku docker-options:add local-app deploy \"--add-host=host.docker.internal:host-gateway\"\n\n# set the SERVICE_HOST to the mapped hostname\ndokku config:set local-app SERVICE_HOST=host.docker.internal\n\n# set the SERVICE_PORT to the port combination for your app\ndokku config:set local-app SERVICE_PORT=8080\n\n# set the domains desired\ndokku domains:set local-app local-app.dokku.me\n\n# deploy the service-proxy image\ndokku git:from-image local-app dokku/service-proxy:latest\n</code></pre> <p>Only a single <code>$IP:$PORT</code> combination can be routed to for a given app, and that <code>$IP:$PORT</code> combination must be accessible to the service proxy on initial deploy, or the service proxy won't start.</p>"},{"location":"networking/network/#attaching-an-app-to-a-network","title":"Attaching an app to a network","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>Apps will default to being associated with the default <code>bridge</code> network or a network specified by the <code>initial-network</code> network property. Additionally, an app can be attached to <code>attachable</code> networks by changing the <code>attach-post-create</code> or <code>attach-post-deploy</code> network properties when using the docker-local scheduler. A change in these values will require an app deploy or rebuild.</p> <pre><code># associates the network after a container is created but before it is started\n# commonly used for cross-app networking\ndokku network:set node-js-app attach-post-create test-network\n\n# associates the network after the deploy is successful but before the proxy is updated\n# used for cross-app networking when healthchecks must be invoked first\ndokku network:set node-js-app attach-post-deploy other-test-network\n\n# associates the network at container creation\n# typically blocks access to services and external routing\ndokku network:set node-js-app initial-network global-network\n</code></pre> <p>Multiple networks can also be specified for the <code>attach-post-create</code> and <code>attach-post-deploy</code> phases.</p> <pre><code># one or more networks can be specified\ndokku network:set node-js-app attach-post-create test-network test-network-2\n</code></pre> <p>Setting the <code>attach</code> network property to an empty value will de-associate the container with the network.</p> <pre><code>dokku network:set node-js-app attach-post-create\ndokku network:set node-js-app attach-post-deploy\ndokku network:set node-js-app initial-network\n</code></pre> <p>The network properties can also be set globally. The global default value is an empty string, and the global value is used when no app-specific value is set.</p> <pre><code>dokku network:set --global attach-post-create global-create-network\ndokku network:set --global attach-post-deploy global-deploy-network\ndokku network:set --global initial-network global-network\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku network:set --global attach-post-create\ndokku network:set --global attach-post-deploy\ndokku network:set --global initial-network\n</code></pre>"},{"location":"networking/network/#network-aliases","title":"Network Aliases","text":"<p>Note</p> <p>This feature is only available when an app has been attached to a network other than the default <code>bridge</code> network.</p> <p>When a container created for a deployment is being attached to a network - regardless of which network property was used - a network alias of the pattern <code>APP.PROC_TYPE</code> will be added to all containers. This can be used to load-balance requests between containers. For an application named <code>node-js-app</code> with a process type of web, the network alias - or resolvable DNS record within the network - will be:</p> <pre><code>node-js-app.web\n</code></pre> <p>The fully-qualified URL for the resource will depend upon the <code>PORT</code> being listened to by the application. Applications built via buildpacks will have their <code>PORT</code> environment variable set to <code>5000</code>, and as such internal network requests for the above example should point to the following:</p> <pre><code>http://node-js-app.web:5000\n</code></pre> <p>Dockerfile-based applications may listen on other ports. For more information on how ports are specified for applications, please refer to the port management documentation.</p>"},{"location":"networking/network/#specifying-a-custom-tld","title":"Specifying a custom TLD","text":"<p>When attaching applications to networks, a custom TLD can be specified via the <code>network:set</code> command. This TLD is suffixed to the network alias for the application/process-type combination for all networks to which the application is attached, and cannot be customized per network. The default value is an empty string.</p> <p>To specify a TLD of <code>svc.cluster.local</code> for your application, run the following command:</p> <pre><code># replace node-js-app with your application name\ndokku network:set node-js-app tld svc.cluster.local\n</code></pre> <p>With an application named <code>node-js-app</code> and a process-type named <code>web</code>, the above command will turn the network alias into:</p> <pre><code>node-js-app.web.svc.cluster.local\n</code></pre> <p>Note that this has no impact on container port handling, and users must still specify the container port when making internal network requests.</p> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku network:set node-js-app tld\n</code></pre> <p>The <code>tld</code> property can also be set globally. The global default is emty string, and the global value is used when no app-specific value is set.</p> <pre><code>dokku network:set --global tld svc.cluster.local\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku network:set --global tld\n</code></pre>"},{"location":"networking/network/#when-to-attach-containers-to-a-network","title":"When to attach containers to a network","text":"<p>Containers can be attached to a network for a variety of reasons:</p> <ul> <li>A background process in one app needs to communicate to a webservice in another app</li> <li>An app needs to talk to a container not managed by Dokku in a secure manner</li> <li>A custom network that allows transparent access to another host exists and is necessary for an app to run</li> </ul> <p>Whatever the reason, the semantics of the two network hooks are important and are outlined before.</p> <ul> <li><code>attach-post-create</code>:<ul> <li>Phase it applies to:<ul> <li><code>build</code>: Intermediate containers created during the build process.</li> <li><code>deploy</code>: Deployed app containers.</li> <li><code>run</code>: Containers created by the <code>run</code> command.</li> </ul> </li> <li>Container state on attach: <code>created</code> but not <code>running</code></li> <li>Use case: When the container needs to access a resource on the network.</li> <li>Example: The app needs to talk to a database on the same network when it first boots.</li> </ul> </li> <li><code>attach-post-deploy</code><ul> <li>Phase it applies to:<ul> <li><code>deploy</code>: Deployed app containers.</li> </ul> </li> <li>Container state on attach: <code>running</code></li> <li>Use case: When another container on the network needs to access this container.</li> <li>Example: A background process needs to communicate with the web process exposed by this container.</li> </ul> </li> <li><code>initial-network</code>:<ul> <li>Phase it applies to:<ul> <li><code>build</code>: Intermediate containers created during the build process.</li> <li><code>deploy</code>: Deployed app containers.</li> <li><code>run</code>: Containers created by the <code>run</code> command.</li> </ul> </li> <li>Container state on attach: <code>created</code></li> <li>Use case: When another container on the network is already running and needed by this container.</li> <li>Example: A key-value store exposing itself to all your apps may be on the <code>initial-network</code>.</li> </ul> </li> </ul> <p>Warning</p> <p>If the attachment fails during the <code>running</code> container state, this may result in your application failing to respond to proxied requests once older containers are removed.</p>"},{"location":"networking/network/#rebuilding-network-settings","title":"Rebuilding network settings","text":"<p>There are cases where you may need to rebuild the network configuration for an app, such as on app boot or container restart. In these cases, you can use the <code>network:rebuild</code> command:</p> <pre><code>dokku network:rebuild node-js-app\n</code></pre> <p>Info</p> <p>This command will exit a non-zero number that depends on the number of containers for which configuration could not be built</p>"},{"location":"networking/network/#rebuilding-all-network-settings","title":"Rebuilding all network settings","text":"<p>In some cases, a docker upgrade may reset container IPs or Ports. In both cases, you can quickly rewrite those files by using the <code>network:rebuildall</code> command:</p> <pre><code>dokku network:rebuildall\n</code></pre> <p>Info</p> <p>This command will exit a non-zero number that depends on the number of containers for which configuration could not be built</p>"},{"location":"networking/network/#container-network-interface-binding","title":"Container network interface binding","text":"<p>Info</p> <p>This functionality does not control the <code>--network</code> docker flag. Please use the docker-options plugin to manage this flag.</p> <p>By default, an app will only bind to the internal interface. This behavior can be modified per app by changing the <code>bind-all-interfaces</code> network property.</p> <pre><code># bind to the default docker interface (`docker0`) with a random internal ip\n# this is the default behavior\ndokku network:set node-js-app bind-all-interfaces false\n\n# bind to all interfaces (`0.0.0.0`) on a random port for each upstream port\n# this will make the app container directly accessible by other hosts on your network\n# ports are randomized for every deploy, e.g. `0.0.0.0:32771-&gt;5000/tcp`.\ndokku network:set node-js-app bind-all-interfaces true\n</code></pre> <p>By way of example, in the default case, each container is bound to the docker interface:</p> ShellOutput <pre><code>docker ps\n</code></pre> <pre><code>CONTAINER ID        IMAGE                      COMMAND                CREATED              STATUS              PORTS               NAMES\n1b88d8aec3d1        dokku/node-js-app:latest   \"/bin/bash -c '/star   About a minute ago   Up About a minute                       node-js-app.web.1\n</code></pre> <p>As such, the container's IP address will be an internal IP, and thus it is only accessible on the host itself:</p> ShellOutput <pre><code>docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' node-js-app.web.1\n</code></pre> <pre><code>172.17.0.6\n</code></pre> <p>However, you can disable the internal proxying via the <code>network:set</code> command so that it will listen on the host's IP address:</p> ShellOutput <pre><code>dokku network:set node-js-app bind-all-interfaces true\n\n# container bound to all interfaces\ndocker ps\n</code></pre> <pre><code>CONTAINER ID        IMAGE                      COMMAND                CREATED              STATUS              PORTS                     NAMES\nd6499edb0edb        dokku/node-js-app:latest   \"/bin/bash -c '/star   About a minute ago   Up About a minute   0.0.0.0:49153-&gt;5000/tcp   node-js-app.web.1\n</code></pre> <p>The <code>bind-all-interfaces</code> property can also be set globally. The global default is <code>false</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku network:set --global bind-all-interfaces true\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku network:set --global bind-all-interfaces\n</code></pre>"},{"location":"networking/network/#displaying-network-reports-for-an-app","title":"Displaying network reports for an app","text":"<p>You can get a report about the app's network status using the <code>network:report</code> command:</p> ShellOutput <pre><code>dokku network:report\n</code></pre> <pre><code>=====&gt; node-js-app network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners: 172.17.0.1:5000\n=====&gt; python-sample network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners:          172.17.0.2:5000\n=====&gt; ruby-sample network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku network:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners: 172.17.0.1:5000\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku network:report node-js-app --network-bind-all-interfaces\n</code></pre>"},{"location":"networking/port-management/","title":"Port Management","text":"<p>New</p> <p>Introduced in 0.31.0, replaces the previous <code>proxy:ports*</code> commands</p> <pre><code>ports:list &lt;app&gt;                        # List port mappings for an app\nports:add &lt;app&gt; &lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt; [&lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt;...]           # Add port mappings to an app\nports:clear &lt;app&gt;                       # Clear all port mappings for an app\nports:remove &lt;app&gt; &lt;host-port&gt; [&lt;host-port&gt;|&lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt;...]                      # Remove specific port mappings from an app\nports:set &lt;app&gt; &lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt; [&lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt;...]           # Set port mappings for an app\n</code></pre>"},{"location":"networking/port-management/#usage","title":"Usage","text":"<p>Warning</p> <p>Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable.</p> <p>Users should also avoid setting the <code>PORT</code> environment variable. Dokku will use port mappings to set this value. Overriding this manually may cause issues in application routing.</p> <p>You can now configure <code>host -&gt; container</code> port mappings with the <code>ports:*</code> commands. This mapping is currently supported by the built-in nginx-vhosts plugin.</p> <p>By default, buildpack apps and dockerfile apps without explicitly exposed ports (i.e. using the <code>EXPOSE</code> directive) will be configured with a listener on port <code>80</code> (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port <code>5000</code>. Dockerfile apps with explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.</p> <p>Note</p> <p>This default behavior will not be automatically changed on subsequent pushes and must be manipulated with the <code>ports:*</code> commands detailed below.</p>"},{"location":"networking/port-management/#port-scheme","title":"Port Scheme","text":"<p>The proxy port scheme is as follows:</p> <ul> <li><code>SCHEME:HOST_PORT:CONTAINER_PORT</code></li> </ul> <p>The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in <code>nginx-vhosts</code> proxy implementation supports the <code>http</code>, <code>https</code>, <code>grpc</code> and <code>grpcs</code> schemes. For the <code>grpc</code> and <code>grpcs</code> see nginx blog post on grpc.</p> <p>Developers of proxy implementations are encouraged to use whatever schemes make the most sense, and ignore configurations which they do not support. For instance, a <code>udp</code> proxy implementation can safely ignore <code>http</code> and <code>https</code> port mappings.</p> <p>To change the proxy implementation in use for an application, use the <code>proxy:set</code> command:</p> <pre><code># no validation will be performed against\n# the specified proxy implementation\ndokku proxy:set node-js-app nginx\n</code></pre>"},{"location":"networking/port-management/#listing-port-mappings","title":"Listing port mappings","text":"<p>To inspect the port mapping for a given application, use the <code>ports:list</code> command:</p> ShellOutput <pre><code>dokku ports:list node-js-app\n</code></pre> <pre><code>-----&gt; Port mappings for node-js-app\n-----&gt; scheme             host port                 container port\nhttp                      80                        5000\n</code></pre> <p>The above application is listening on the host's port <code>80</code>, which we can test via curl:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me\n</code></pre> <pre><code>Hello World!\n</code></pre>"},{"location":"networking/port-management/#adding-a-custom-port-mapping","title":"Adding a custom port mapping","text":"<p>There are cases where we may wish for the service to be listening on more than one port, such as port 8080. Normally, this would not be possible:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me:8080\n</code></pre> <pre><code>curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused\n</code></pre> <p>However, we can use the <code>ports:add</code> command to add a second external port mapping - <code>8080</code> - to our application's port <code>5000</code>.</p> ShellOutput <pre><code>dokku ports:add node-js-app http:8080:5000\n</code></pre> <pre><code>-----&gt; Configuring node-js-app.dokku.me...(using built-in template)\n-----&gt; Creating http nginx.conf\n       Reloading nginx\n</code></pre> <p>We can now test that port 80 still responds properly:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me\n</code></pre> <pre><code>Hello World!\n</code></pre> <p>And our new listening port of <code>8080</code> also works:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me:8080\n</code></pre> <pre><code>Hello World!\n</code></pre>"},{"location":"networking/port-management/#setting-all-port-mappings-at-once","title":"Setting all port mappings at once","text":"<p>Port mappings can also be force set using the <code>ports:set</code> command.</p> ShellOutput <pre><code>dokku ports:set node-js-app http:8080:5000\n</code></pre> <pre><code>-----&gt; Configuring node-js-app.dokku.me...(using built-in template)\n-----&gt; Creating http nginx.conf\n       Reloading nginx\n</code></pre>"},{"location":"networking/port-management/#removing-a-port-mapping","title":"Removing a port mapping","text":"<p>A port mapping can be removed using the <code>ports:remove</code> command if it no longer necessary:</p> <pre><code>dokku ports:remove node-js-app http:80:5000\n</code></pre> <p>Ports may also be removed by specifying only the <code>host-port</code> value. This effectively acts as a wildcard and removes all mappings for that particular host port.</p> <pre><code>dokku ports:remove node-js-app http:80\n</code></pre>"},{"location":"networking/port-management/#port-management-by-deployment-method","title":"Port management by Deployment Method","text":"<p>Warning</p> <p>If you set a port map but do not have a global domain set, Dokku will reset that map upon first deployment.</p>"},{"location":"networking/port-management/#buildpacks","title":"Buildpacks","text":"<p>For buildpack deployments, your application must respect the <code>PORT</code> environment variable. We will typically set this to port <code>5000</code>, but this is not guaranteed. If you do not respect the <code>PORT</code> environment variable, your containers may start but your services will not be accessible outside of that container.</p>"},{"location":"networking/port-management/#dockerfile","title":"Dockerfile","text":"<p>Info</p> <p>Changed as of 0.5.0</p> <p>Dokku's default proxy implementation - nginx - supports HTTP and GRPC request proxying. At this time, we do not support proxying plain TCP or UDP ports. UDP ports can be exposed by disabling the nginx proxy with <code>dokku proxy:disable myapp</code> and manually exposing the ports via the <code>docker-options</code> plugin. For example, <code>dokku docker-options:add myapp deploy \"-p 2456:2456/udp\"</code>. If you would like to investigate alternative proxy methods, please refer to our proxy management documentation.</p>"},{"location":"networking/port-management/#applications-using-expose","title":"Applications using EXPOSE","text":"<p>Dokku will extract all tcp ports exposed using the <code>EXPOSE</code> directive (one port per line) and setup nginx to proxy the same port numbers to listen publicly. If you would like to change the exposed port, you should do so within your <code>Dockerfile</code>.</p> <p>For example, if the Dokku installation is configured with the domain <code>dokku.me</code> and an application named <code>node-js-app</code> is deployed with following Dockerfile:</p> <pre><code>FROM ubuntu:20.04\nEXPOSE 1234\nRUN python -m SimpleHTTPServer 1234\n</code></pre> <p>The application would be exposed to the user at <code>node-js-app.dokku.me:1234</code>. If this is not desired, the following application configuration may be applied:</p> <pre><code># add a port mapping to port 80\ndokku ports:add node-js-app http:80:1234\n\n# remove the incorrect port mapping\ndokku ports:remove node-js-app http:1234:1234\n</code></pre>"},{"location":"networking/port-management/#applications-not-using-expose","title":"Applications not using EXPOSE","text":"<p>Any application that does not use an <code>EXPOSE</code> directive will result in Dokku defaulting to port <code>5000</code>. This behavior mimics the behavior of a Buildpack deploy. If your application does not support the <code>PORT</code> environment variable, then you will either need to:</p> <ul> <li>modify your application to support the <code>PORT</code> environment variable.</li> <li>switch to using an <code>EXPOSE</code> directive in your Dockerfile.</li> </ul>"},{"location":"networking/port-management/#displaying-ports-reports-for-an-app","title":"Displaying ports reports for an app","text":"<p>You can get a report about the app's ports status using the <code>ports:report</code> command:</p> ShellOutput <pre><code>dokku ports:report\n</code></pre> <pre><code>=====&gt; node-js-app ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000 https:443:5000\n=====&gt; python-sample ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000\n=====&gt; ruby-sample ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku ports:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000 https:443:5000\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku ports:report node-js-app --ports-map\n</code></pre>"},{"location":"networking/proxy-management/","title":"Proxy Management","text":"<p>New</p> <p>Introduced in 0.5.0, Enhanced in 0.6.0</p> <pre><code>proxy:build-config [--parallel count] [--all|&lt;app&gt;] # (Re)builds config for given app\nproxy:clear-config [--all|&lt;app&gt;] # Clears config for given app\nproxy:disable [--parallel count] [--all|&lt;app&gt;]      # Disable proxy for app\nproxy:enable [--parallel count] [--all|&lt;app&gt;]       # Enable proxy for app\nproxy:report [&lt;app&gt;] [&lt;flag&gt;]                       # Displays a proxy report for one or more apps\nproxy:set [&lt;app&gt;|--global] &lt;proxy-type&gt;                        # Set proxy type for app\n</code></pre> <p>In Dokku 0.5.0, port proxying was decoupled from the <code>nginx-vhosts</code> plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. In the future this will allow other proxy software - such as HAProxy or Caddy - to be used in place of nginx.</p>"},{"location":"networking/proxy-management/#usage","title":"Usage","text":""},{"location":"networking/proxy-management/#changing-the-proxy","title":"Changing the proxy","text":"<p>The default proxy shipped with Dokku is <code>nginx</code>. It can be changed via the <code>proxy:set</code> command.</p> ShellOutput <pre><code>dokku proxy:set node-js-app caddy\n</code></pre> <pre><code>-----&gt; Setting config vars\n       DOKKU_APP_PROXY_TYPE:  caddy\n</code></pre> <p>The proxy may also be set on a global basis. This is usually preferred as running multiple proxy implementations may cause port collision issues.</p> ShellOutput <pre><code>dokku proxy:set --global caddy\n</code></pre> <pre><code>-----&gt; Setting config vars\n       DOKKU_PROXY_TYPE:  caddy\n</code></pre> <p>Changing the proxy does not stop or start any given proxy implementation. Please see the documentation for your proxy implementation for details on how to perform a change.</p>"},{"location":"networking/proxy-management/#regenerating-proxy-config","title":"Regenerating proxy config","text":"<p>In certain cases, your app proxy configs may drift from the correct config for your app. You may regenerate the config at any point via the <code>proxy:build-config</code> command. This command will trigger a rebuild for the configured proxy implementation (default: nginx) for a given app. The command may fail if there are no current web listeners for your app.</p> <pre><code>dokku proxy:build-config node-js-app\n</code></pre> <p>All apps may have their proxy config rebuilt by using the <code>--all</code> flag.</p> <pre><code>dokku proxy:build-config --all\n</code></pre> <p>By default, rebuilding proxy configs for all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku proxy:build-config --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku proxy:build-config --all --parallel -1\n</code></pre>"},{"location":"networking/proxy-management/#clearing-the-generated-proxy-config","title":"Clearing the generated proxy config","text":"<p>New</p> <p>Introduced in 0.27.0</p> <p>Generated proxy configurations can also be cleared using the <code>proxy:clear-config</code> command.</p> <pre><code>dokku proxy:clear-config node-js-app\n</code></pre> <p>All apps may have their proxy config cleared by using the <code>--all</code> flag.</p> <pre><code>dokku proxy:clear-config --all\n</code></pre> <p>Clearing a proxy configuration has different effects depending on the proxy plugin in use. Consul the documentation for your proxy implementation for further details.</p>"},{"location":"networking/proxy-management/#displaying-proxy-reports-for-an-app","title":"Displaying proxy reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's proxy status using the <code>proxy:report</code> command:</p> ShellOutput <pre><code>dokku proxy:report\n</code></pre> <pre><code>=====&gt; node-js-app proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n=====&gt; python-sample proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n=====&gt; ruby-sample proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku proxy:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku proxy:report node-js-app --proxy-type\n</code></pre>"},{"location":"networking/proxy-management/#proxy-port-scheme","title":"Proxy Port Scheme","text":"<p>See the port scheme documentation for more information on the port mapping scheme used by dokku.</p>"},{"location":"networking/proxy-management/#proxy-port-mapping","title":"Proxy port mapping","text":"<p>See the port management documentation for more information on how port mappings are managed for an application.</p>"},{"location":"networking/proxy-management/#container-network-interface-binding","title":"Container network interface binding","text":"<p>Info</p> <p>Changed as of 0.11.0</p> <p>From Dokku versions <code>0.5.0</code> until <code>0.11.0</code>, enabling or disabling an application's proxy would also control whether or not the application was bound to all interfaces - e.g. <code>0.0.0.0</code>. As of <code>0.11.0</code>, this is now controlled by the network plugin. Please see the network documentation for more information.</p>"},{"location":"networking/proxy-management/#implementing-a-proxy","title":"Implementing a Proxy","text":"<p>Custom plugins names must have the suffix <code>-vhosts</code> or scheduler overriding via <code>proxy:set</code> may not function as expected.</p> <p>At this time, the following dokku commands are used to interact with a complete proxy implementation.</p> <ul> <li><code>domains:add</code>: Adds a given domain to an app.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>domains:clear</code>: Clears out an app's associated domains.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>domains:disable</code>: Disables domains for an app.<ul> <li>triggers: <code>pre-disable-vhost</code></li> </ul> </li> <li><code>domains:enable</code>: Enables domains for an app.<ul> <li>triggers: <code>pre-enable-vhost</code></li> </ul> </li> <li><code>domains:remove</code>: Removes a domain from an app.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>domains:set</code>: Sets all domains for a given app.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>proxy:build-config</code>: Builds - or rebuilds - external proxy configuration.<ul> <li>triggers: <code>proxy-build-config</code></li> </ul> </li> <li><code>proxy:clear-config</code>: Clears out external proxy configuration.<ul> <li>triggers: <code>proxy-clear-config</code></li> </ul> </li> <li><code>proxy:disable</code>: Disables the proxy configuration for an app.<ul> <li>triggers: <code>proxy-disable</code></li> </ul> </li> <li><code>proxy:enable</code>: Enables the proxy configuration for an app.<ul> <li>triggers: <code>proxy-enable</code></li> </ul> </li> <li><code>ports:add</code>: Adds one or more port mappings to an app<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> <li><code>ports:clear</code>: Clears out all port mappings for an app.<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> <li><code>ports:remove</code>: Removes one or more port mappings from an app.<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> <li><code>ports:set</code>: Sets all port mappings for an app.<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> </ul> <p>Proxy implementations may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins.</p> <p>Individual proxy implementations may trigger app rebuilds, depending on how proxy metadata is exposed for the proxy implementation.</p> <p>Finally, proxy implementations may install extra software needed for the proxy itself in whatever manner deemed fit. Proxy software can run on the host itself or within a running Docker container with either exposed ports or host networking.</p>"},{"location":"networking/proxies/caddy/","title":"Caddy Proxy","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>Dokku provides integration with the Caddy proxy service by utilizing the Docker label-based integration implemented by Caddy.</p> <pre><code>caddy:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a caddy report for one or more apps\ncaddy:logs [--num num] [--tail]          # Display caddy log output\ncaddy:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an caddy property for an app\ncaddy:show-config &lt;app&gt;                  # Display caddy compose config\ncaddy:start                              # Starts the caddy server\ncaddy:stop                               # Stops the caddy server\n</code></pre>"},{"location":"networking/proxies/caddy/#requirements","title":"Requirements","text":"<p>Using the <code>caddy</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/caddy/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy.</p> <p>The Caddy plugin has specific rules for routing requests:</p> <ul> <li>Caddy integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While Caddy will respect labels associated with other containers, only <code>web</code> containers have Caddy labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported.</li> <li>Caddy will automatically enable SSL if the letsencrypt email property is set. SSL will be disabled otherwise.</li> <li>If no <code>http:80</code> mapping is found, the first <code>http</code> port mapping is used for http requests.</li> <li>If no <code>https:443</code> mapping is found, the first <code>https</code> port mapping is used for https requests.</li> <li>If no <code>https</code> mapping is found, the container port from <code>http:80</code> will be used for https requests.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/caddy/#switching-to-caddy","title":"Switching to Caddy","text":"<p>To use the Caddy plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app caddy\n</code></pre> <p>This will enable the docker label-based Caddy integration. All future deploys will inject the correct labels for Caddy to read and route requests to containers. Due to the docker label-based integration used by Caddy, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/caddy/#starting-caddy-container","title":"Starting Caddy container","text":"<p>Caddy can be started via the <code>caddy:start</code> command. This will start a Caddy container via the <code>docker compose up</code> command.</p> <pre><code>dokku caddy:start\n</code></pre>"},{"location":"networking/proxies/caddy/#stopping-the-caddy-container","title":"Stopping the Caddy container","text":"<p>Caddy may be stopped via the <code>caddy:stop</code> command.</p> <pre><code>dokku caddy:stop\n</code></pre> <p>The Caddy container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/caddy/#showing-the-caddy-compose-config","title":"Showing the Caddy compose config","text":"<p>For debugging purposes, it may be useful to show the Caddy compose config. This can be achieved via the <code>caddy:show-config</code> command.</p> <pre><code>dokku caddy:show-config\n</code></pre>"},{"location":"networking/proxies/caddy/#customizing-the-caddy-container-image","title":"Customizing the Caddy container image","text":"<p>While the default Caddy image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global image lucaslorentz/caddy-docker-proxy:2.7\n</code></pre>"},{"location":"networking/proxies/caddy/#checking-the-caddy-containers-logs","title":"Checking the Caddy container's logs","text":"<p>It may be necessary to check the Caddy container's logs to ensure that Caddy is operating as expected. This can be performed with the <code>caddy:logs</code> command.</p> <pre><code>dokku caddy:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku caddy:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the caddy container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/caddy/#changing-the-caddy-log-level","title":"Changing the Caddy log level","text":"<p>Caddy log output is set to <code>ERROR</code> by default. It may be changed by setting the <code>log-level</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global log-level DEBUG\n</code></pre> <p>After modifying,  the Caddy container will need to be restarted.</p>"},{"location":"networking/proxies/caddy/#ssl-configuration","title":"SSL Configuration","text":"<p>The caddy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/caddy/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, the Caddy container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/caddy/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the Caddy container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/caddy/#using-caddys-internal-tls-server","title":"Using Caddy's Internal TLS server","text":"<p>To switch to Caddy's internal TLS server for certificate provisioning, set the <code>tls-internal</code> property. This can only be set on a per-app basis.</p> <pre><code>dokku caddy:set node-js-app tls-internal true\n</code></pre>"},{"location":"networking/proxies/caddy/#displaying-caddy-reports-for-an-app","title":"Displaying Caddy reports for an app","text":"<p>You can get a report about the app's Caddy config using the <code>caddy:report</code> command:</p> ShellOutput <pre><code>dokku caddy:report\n</code></pre> <pre><code>=====&gt; node-js-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n=====&gt; python-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n=====&gt; ruby-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku caddy:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku caddy:report node-js-app --caddy-image\n</code></pre>"},{"location":"networking/proxies/haproxy/","title":"Haproxy Proxy","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>Dokku provides integration with the Haproxy proxy service by utilizing the Docker label-based integration implemented by EasyHaproxy.</p> <pre><code>haproxy:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a haproxy report for one or more apps\nhaproxy:logs [--num num] [--tail]          # Display haproxy log output\nhaproxy:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an haproxy property for an app\nhaproxy:show-config &lt;app&gt;                  # Display haproxy compose config\nhaproxy:start                              # Starts the haproxy server\nhaproxy:stop                               # Stops the haproxy server\n</code></pre>"},{"location":"networking/proxies/haproxy/#requirements","title":"Requirements","text":"<p>Using the <code>haproxy</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/haproxy/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy.</p> <p>The Haproxy plugin has specific rules for routing requests:</p> <ul> <li>Haproxy integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While Haproxy will respect labels associated with other containers, only <code>web</code> containers have Haproxy labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported at this time.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/haproxy/#switching-to-haproxy","title":"Switching to Haproxy","text":"<p>To use the Haproxy plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app haproxy\n</code></pre> <p>This will enable the docker label-based Haproxy integration. All future deploys will inject the correct labels for Haproxy to read and route requests to containers. Due to the docker label-based integration used by Haproxy, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/haproxy/#starting-haproxy-container","title":"Starting Haproxy container","text":"<p>Haproxy can be started via the <code>haproxy:start</code> command. This will start a Haproxy container via the <code>docker compose up</code> command.</p> <pre><code>dokku haproxy:start\n</code></pre>"},{"location":"networking/proxies/haproxy/#stopping-the-haproxy-container","title":"Stopping the Haproxy container","text":"<p>Haproxy may be stopped via the <code>haproxy:stop</code> command.</p> <pre><code>dokku haproxy:stop\n</code></pre> <p>The Haproxy container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/haproxy/#showing-the-haproxy-compose-config","title":"Showing the Haproxy compose config","text":"<p>For debugging purposes, it may be useful to show the Haproxy compose config. This can be achieved via the <code>haproxy:show-config</code> command.</p> <pre><code>dokku haproxy:show-config\n</code></pre>"},{"location":"networking/proxies/haproxy/#customizing-the-haproxy-container-image","title":"Customizing the Haproxy container image","text":"<p>While the default Haproxy image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global image byjg/easy-haproxy:4.0.0\n</code></pre>"},{"location":"networking/proxies/haproxy/#checking-the-haproxy-containers-logs","title":"Checking the Haproxy container's logs","text":"<p>It may be necessary to check the Haproxy container's logs to ensure that Haproxy is operating as expected. This can be performed with the <code>haproxy:logs</code> command.</p> <pre><code>dokku haproxy:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku haproxy:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the vector container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/haproxy/#changing-the-haproxy-log-level","title":"Changing the Haproxy log level","text":"<p>Haproxy log output is set to <code>ERROR</code> by default. It may be changed by setting the <code>log-level</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global log-level DEBUG\n</code></pre> <p>After modifying,  the Haproxy container will need to be restarted.</p>"},{"location":"networking/proxies/haproxy/#ssl-configuration","title":"SSL Configuration","text":"<p>The haproxy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/haproxy/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, the Haproxy container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/haproxy/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the Haproxy container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/haproxy/#displaying-haproxy-reports-for-an-app","title":"Displaying Haproxy reports for an app","text":"<p>You can get a report about the app's Haproxy config using the <code>haproxy:report</code> command:</p> ShellOutput <pre><code>dokku haproxy:report\n</code></pre> <pre><code>=====&gt; node-js-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n=====&gt; python-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n=====&gt; ruby-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku haproxy:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku haproxy:report node-js-app --haproxy-image\n</code></pre>"},{"location":"networking/proxies/nginx/","title":"Nginx Proxy","text":"<p>Dokku uses nginx as its server for routing requests to specific applications. By default, access and error logs are written for each app to <code>/var/log/nginx/${APP}-access.log</code> and <code>/var/log/nginx/${APP}-error.log</code> respectively</p> <pre><code>nginx:access-logs &lt;app&gt; [-t]             # Show the nginx access logs for an application (-t follows)\nnginx:error-logs &lt;app&gt; [-t]              # Show the nginx error logs for an application (-t follows)\nnginx:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a nginx report for one or more apps\nnginx:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an nginx property for an app\nnginx:show-config &lt;app&gt;                  # Display app nginx config\nnginx:start                              # Starts the nginx server\nnginx:stop                               # Stops the nginx server\nnginx:validate-config [&lt;app&gt;] [--clean]  # Validates and optionally cleans up invalid nginx configurations\n</code></pre>"},{"location":"networking/proxies/nginx/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided.</p>"},{"location":"networking/proxies/nginx/#request-proxying","title":"Request Proxying","text":"<p>By default, the <code>web</code> process is the only process proxied by the nginx proxy implementation. Proxying to other process types may be handled by a custom <code>nginx.conf.sigil</code> file, as generally described below</p> <p>Nginx will proxy the requests in a round-robin balancing fashion to the different deployed (scaled) containers running the <code>web</code> proctype. This way, the host's resources can be fully leveraged for single-threaded applications (e.g. <code>dokku ps:scale node-js-app web=4</code> on a 4-core machine).</p> <p>Note</p> <p>Due to how the plugin is implemented, if an app successfully starts up <code>web</code> containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger <code>dokku proxy:build-config $APP</code> in order to ensure requests route to the new web containers.</p>"},{"location":"networking/proxies/nginx/#starting-nginx","title":"Starting nginx","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>The nginx server can be started via <code>nginx:start</code>.</p> <pre><code>dokku nginx:start\n</code></pre>"},{"location":"networking/proxies/nginx/#stopping-nginx","title":"Stopping nginx","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>The nginx server can be stopped via <code>nginx:stop</code>.</p> <pre><code>dokku nginx:stop\n</code></pre>"},{"location":"networking/proxies/nginx/#binding-to-specific-addresses","title":"Binding to specific addresses","text":"<p>New</p> <p>Introduced in 0.19.2</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>By default, nginx will listen to all interfaces (<code>[::]</code> for IPv6, <code>0.0.0.0</code> for IPv4) when proxying requests to applications. This may be changed using the <code>bind-address-ipv4</code> and <code>bind-address-ipv6</code> properties. This is useful in cases where the proxying should be internal to a network or if there are multiple network interfaces that should respond with different content.</p> <pre><code>dokku nginx:set node-js-app bind-address-ipv4 127.0.0.1\ndokku nginx:set node-js-app bind-address-ipv6 ::1\n</code></pre> <p>This may be reverted by setting an empty bind address.</p> <pre><code>dokku nginx:set node-js-app bind-address-ipv4\ndokku nginx:set node-js-app bind-address-ipv6\n</code></pre> <p>Warning</p> <p>Validation is not performed on either value.</p> <p>Users with apps that contain a custom <code>nginx.conf.sigil</code> file will need to modify the files to respect the new <code>NGINX_BIND_ADDRESS_IPV4</code> and <code>NGINX_BIND_ADDRESS_IPV6</code> variables.</p>"},{"location":"networking/proxies/nginx/#hsts-header","title":"HSTS Header","text":"<p>New</p> <p>Introduced in 0.20.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via <code>nginx:set</code>:</p> <pre><code>dokku nginx:set node-js-app hsts true\ndokku nginx:set node-js-app hsts false\n</code></pre> <p>The following options are also available via the <code>nginx:set</code> command:</p> <ul> <li><code>hsts</code> (type: boolean, default: <code>true</code>): Enables or disables HSTS for your application.</li> <li><code>hsts-include-subdomains</code> (type: boolean, default: <code>true</code>): Tells the browser that the HSTS policy also applies to all subdomains of the current domain.</li> <li><code>hsts-max-age</code> (type: integer, default: <code>15724800</code>): Time in seconds to cache HSTS configuration.</li> <li><code>hsts-preload</code> (type: boolean, default: <code>false</code>): Tells most major web browsers to include the domain in their HSTS preload lists.</li> </ul> <p>Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails until the max-age is reached.</p>"},{"location":"networking/proxies/nginx/#globally-disabling-the-hsts-header","title":"Globally disabling the HSTS Header","text":"<p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>HSTS Header can be disabled for all apps by setting the <code>hsts</code> property to false after passing the <code>--global</code> flag to <code>nginx:set</code>.</p> <pre><code>dokku nginx:set --global hsts false\n</code></pre> <p>Once the HSTS setting is disabled globally, it can be re-enabled on a per-app basis by setting the <code>hsts</code> property as normal.</p> <pre><code>dokku nginx:set node-js-app hsts true\n</code></pre>"},{"location":"networking/proxies/nginx/#running-behind-another-proxy-configuring-x-forwarded-headers","title":"Running behind another proxy \u2014 configuring <code>X-Forwarded-*</code> headers","text":"<p>Dokku's default Nginx configuration passes the de-facto standard HTTP headers <code>X-Forwarded-For</code>, <code>X-Forwarded-Proto</code>, and <code>X-Forwarded-Port</code> to your application. These headers indicate the IP address of the original client making the request, the protocol of the original request (HTTP or HTTPS), and the port number of the original request, respectively.</p> <p>If you have another HTTP proxy sitting in between the end user and your server (for example, a load balancer, or a CDN), then the values of these headers will contain information about (e.g. the IP address of) the the closest proxy, and not the end user.</p> <p>To fix this, assuming that the other proxy also passes <code>X-Forwarded-*</code> headers, which in turn contain information about the end user, you can tell Nginx include those values in the <code>X-Forwarded-*</code> headers that it sends to your application. You can do this via <code>nginx:set</code>, like so:</p> <pre><code>dokku nginx:set node-js-app x-forwarded-for-value '$http_x_forwarded_for'\ndokku nginx:set node-js-app x-forwarded-port-value '$http_x_forwarded_port'\ndokku nginx:set node-js-app x-forwarded-proto-value '$http_x_forwarded_proto'\n</code></pre> <p>However, note that you should only do this if:</p> <ol> <li>Requests to your website always go through a trusted proxy.</li> <li>That proxy is configured to send the aforementioned <code>X-Forwarded-*</code> headers.</li> </ol> <p>Otherwise, if it's possible for clients to make HTTP requests directly against your server, bypassing the other proxy, or if the other proxy is not configured to set these headers, then a client can basically pass any arbitrary values for these headers (which your app then presumably reads) and thereby fake an IP address, for example.</p> <p>There's also the <code>X-Forwarded-Ssl</code> header which a less common alternative to <code>X-Forwarded-Proto</code> \u2014 and because of that, isn't included in Dokku's default Nginx configuration. But you can tell Nginx to send this header as well, if necessary.</p> <pre><code># force-setting value to `on`\ndokku nginx:set node-js-app x-forwarded-ssl on\n\n# force-setting value to `off`\ndokku nginx:set node-js-app x-forwarded-ssl off\n\n# removing the value from nginx.conf (default)\ndokku nginx:set node-js-app x-forwarded-ssl\n</code></pre>"},{"location":"networking/proxies/nginx/#checking-access-logs","title":"Checking access logs","text":"<p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>You may check nginx access logs via the <code>nginx:access-logs</code> command. This assumes that app access logs are being stored in <code>/var/log/nginx/$APP-access.log</code>, as is the default in the generated <code>nginx.conf</code>.</p> <pre><code>dokku nginx:access-logs node-js-app\n</code></pre> <p>You may also follow the logs by specifying the <code>-t</code> flag.</p> <pre><code>dokku nginx:access-logs node-js-app -t\n</code></pre>"},{"location":"networking/proxies/nginx/#checking-error-logs","title":"Checking error logs","text":"<p>You may check nginx error logs via the <code>nginx:error-logs</code> command. This assumes that app error logs are being stored in <code>/var/log/nginx/$APP-error.log</code>, as is the default in the generated <code>nginx.conf</code>.</p> <pre><code>dokku nginx:error-logs node-js-app\n</code></pre> <p>You may also follow the logs by specifying the <code>-t</code> flag.</p> <pre><code>dokku nginx:error-logs node-js-app -t\n</code></pre>"},{"location":"networking/proxies/nginx/#changing-log-path","title":"Changing log path","text":"<p>New</p> <p>Introduced in 0.20.1</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>The path to where log files are stored can be changed by calling the <code>nginx:set</code> command with the following options:</p> <ul> <li><code>access-log-path</code> (type: string, default: <code>${NGINX_LOG_ROOT}/${APP}-access.log</code>): Log path for nginx access logs</li> <li><code>error-log-path</code> (type: string, default: <code>${NGINX_LOG_ROOT}/${APP}-error.log</code>): Log path for nginx error logs</li> </ul> <p>The defaults should not be changed without verifying that the paths will be writeable by nginx. However, this setting is useful for enabling or disabling logging by setting the values to <code>off</code>.</p> <pre><code>dokku nginx:set node-js-app access-log-path off\ndokku nginx:set node-js-app error-log-path off\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku nginx:set node-js-app access-log-path\ndokku nginx:set node-js-app error-log-path\n</code></pre> <p>In all cases, the nginx config must be regenerated after setting the above values.</p>"},{"location":"networking/proxies/nginx/#changing-log-format","title":"Changing log format","text":"<p>New</p> <p>Introduced in 0.22.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>The format of the access log can be changed by calling the <code>nginx:set</code> command as follows:</p> <pre><code>dokku nginx:set node-js-app access-log-format custom-format\n</code></pre> <p>Prior to changing the log-format, log formats should be specified at a file such as <code>/etc/nginx/conf.d/00-log-formats.conf</code>. This will ensure they are available within your app's nginx context. For instance, the following may be added to the above file. It only needs to be specified once to be used for all apps.</p> <pre><code># /etc/nginx/conf.d/00-log-formats.conf\n# escape=json was added in nginx 1.11.8\nlog_format json_combined escape=json\n  '{'\n    '\"time_local\":\"$time_local\",'\n    '\"remote_addr\":\"$remote_addr\",'\n    '\"remote_user\":\"$remote_user\",'\n    '\"request\":\"$request\",'\n    '\"status\":\"$status\",'\n    '\"body_bytes_sent\":\"$body_bytes_sent\",'\n    '\"request_time\":\"$request_time\",'\n    '\"http_referrer\":\"$http_referer\",'\n    '\"http_user_agent\":\"$http_user_agent\"'\n  '}';\n</code></pre> <p>Next, the format should be set for the given app.</p> <pre><code>dokku nginx:set node-js-app access-log-format json_combined\n</code></pre> <p>Finally, a proxy rebuild will change the format as desired.</p> <pre><code>dokku proxy:build-config node-js-app\n</code></pre>"},{"location":"networking/proxies/nginx/#specifying-a-read-timeout","title":"Specifying a read timeout","text":"<p>New</p> <p>Introduced in 0.21.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>When proxying requests to your applications, it may be useful to specify a proxy read timeout. This can be done via the <code>nginx:set</code> command as follows:</p> <pre><code>dokku nginx:set node-js-app proxy-read-timeout 120s\n</code></pre> <p>The default value is <code>60s</code>, and all numeric values must have a trailing time value specified (<code>s</code> for seconds, <code>m</code> for minutes).</p> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku nginx:set node-js-app proxy-read-timeout\n</code></pre> <p>In all cases, the nginx config must be regenerated after setting the above value.</p>"},{"location":"networking/proxies/nginx/#specifying-a-custom-client_max_body_size","title":"Specifying a custom client_max_body_size","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>Users can override the default <code>client_max_body_size</code> value - which limits file uploads - via <code>nginx:set</code>. Changing this value will only apply to every <code>server</code> stanza of the default <code>nginx.conf.sigil</code>; users of custom <code>nginx.conf.sigil</code> files must update their templates to support the new value.</p> <pre><code>dokku nginx:set node-js-app client-max-body-size 50m\n</code></pre> <p>The default value is empty string, which will result in nginx falling back to any configured, higher-level defaults (or <code>1m</code> if unconfigued; all numerical values must have a size unit specified (<code>k</code> for kilobytes, <code>m</code> for megabytes).</p> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku nginx:set node-js-app client-max-body-size\n</code></pre> <p>In all cases, the nginx config must be regenerated after setting the above value.</p> <p>Changing this value when using the PHP buildpack (or any other buildpack that uses an intermediary server) will require changing the value in the server config shipped with that buildpack. Consult your buildpack documentation for further details.</p>"},{"location":"networking/proxies/nginx/#showing-the-nginx-config","title":"Showing the nginx config","text":"<p>For debugging purposes, it may be useful to show the nginx config. This can be achieved via the <code>nginx:show-config</code> command.</p> <pre><code>dokku nginx:show-config node-js-app\n</code></pre>"},{"location":"networking/proxies/nginx/#validating-nginx-configs","title":"Validating nginx configs","text":"<p>It may be desired to validate an nginx config outside of the deployment process. To do so, run the <code>nginx:validate-config</code> command. With no arguments, this will validate all app nginx configs, one at a time. A minimal wrapper nginx config is generated for each app's nginx config, upon which <code>nginx -t</code> will be run.</p> <pre><code>dokku nginx:validate-config\n</code></pre> <p>As app nginx configs are actually executed within a shared context, it is possible for an individual config to be invalid when being validated standalone but also be valid within the global server context. As such, the exit code for the <code>nginx:validate-config</code> command is the exit code of <code>nginx -t</code> against the server's real nginx config.</p> <p>The <code>nginx:validate-config</code> command also takes an optional <code>--clean</code> flag. If specified, invalid nginx configs will be removed.</p> <p>Warning</p> <p>Invalid app nginx config's will be removed even if the config is valid in the global server context.</p> <pre><code>dokku nginx:validate-config --clean\n</code></pre> <p>The <code>--clean</code> flag may also be specified for a given app:</p> <pre><code>dokku nginx:validate-config node-js-app --clean\n</code></pre>"},{"location":"networking/proxies/nginx/#customizing-the-nginx-configuration","title":"Customizing the nginx configuration","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>Dokku uses a templating library by the name of sigil to generate nginx configuration for each app. This may be overriden by committing the default configuration template to a file named <code>nginx.conf.sigil</code> in the root of the app repository.</p> <p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>nginx.conf.sigil</code> file to use for a given app. This can be done via the <code>nginx:set</code> command. If a value is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no <code>nginx.conf.sigil</code>.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>nginx.conf.sigil</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>nginx.conf.sigil</code> extracted directly from the source code. Both cases will respect the configured <code>nginx-conf-sigil-path</code> property value.</p> <pre><code>dokku nginx:set node-js-app nginx-conf-sigil-path .dokku/nginx.conf.sigil\n</code></pre> <p>This property can also be changed globally, which will take into effect if there is no value at the app level.</p> <pre><code>dokku nginx:set --global nginx-conf-sigil-path .dokku/nginx.conf.sigil\n</code></pre> <p>In either case, the value can be reset by specifying an empty value.</p> <pre><code>dokku nginx:set node-js-app nginx-conf-sigil-path\ndokku nginx:set --global nginx-conf-sigil-path\n</code></pre> <p>Info</p> <p>The default template may change with new releases of Dokku. Please refer to the appropriate template file version for your Dokku version, and make sure to look out for changes when you upgrade.</p>"},{"location":"networking/proxies/nginx/#disabling-custom-nginx-config","title":"Disabling custom nginx config","text":"<p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>While enabled by default, using a custom nginx config can be disabled via <code>nginx:set</code>. This may be useful in cases where you do not want to allow users to override any higher-level customization of app nginx config.</p> <pre><code># enable fetching custom config (default)\ndokku nginx:set node-js-app disable-custom-config false\n\n# disable fetching custom config\ndokku nginx:set node-js-app disable-custom-config true\n</code></pre> <p>Unsetting this value is the same as enabling custom nginx config usage.</p>"},{"location":"networking/proxies/nginx/#available-template-variables","title":"Available template variables","text":"<pre><code>{{ .APP }}                          Application name\n{{ .APP_SSL_PATH }}                 Path to SSL certificate and key\n{{ .DOKKU_ROOT }}                   Global Dokku root directory (ex: app dir would be `{{ .DOKKU_ROOT }}/{{ .APP }}`)\n{{ .PROXY_PORT }}                   Non-SSL nginx listener port (same as `DOKKU_PROXY_PORT` config var)\n{{ .PROXY_SSL_PORT }}               SSL nginx listener port (same as `DOKKU_PROXY_SSL_PORT` config var)\n{{ .NOSSL_SERVER_NAME }}            List of non-SSL VHOSTS\n{{ .PROXY_PORT_MAP }}               List of port mappings (same as the `map` ports property)\n{{ .PROXY_UPSTREAM_PORTS }}         List of configured upstream ports (derived from the `map` ports property)\n{{ .SSL_INUSE }}                    Boolean set when an app is SSL-enabled\n{{ .SSL_SERVER_NAME }}              List of SSL VHOSTS\n</code></pre> <p>Finally, each process type has it's network listeners - a list of IP:PORT pairs for the respective app containers - exposed via an <code>.DOKKU_APP_${PROCESS_TYPE}_LISTENERS</code> variable - the <code>PROCESS_TYPE</code> will be upper-cased with hyphens transformed into underscores. Users can use the new variables to expose non-web processes via the nginx proxy.</p> <p>Note</p> <p>Application environment variables are available for use in custom templates. To do so, use the form of <code>{{ var \"FOO\" }}</code> to access a variable named <code>FOO</code>.</p>"},{"location":"networking/proxies/nginx/#customizing-via-configuration-files-included-by-the-default-templates","title":"Customizing via configuration files included by the default templates","text":"<p>The default nginx.conf template will include everything from your apps <code>nginx.conf.d/</code> subdirectory in the main <code>server {}</code> block (see above):</p> <pre><code>include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;\n</code></pre> <p>That means you can put additional configuration in separate files. To increase the client request header timeout, the following can be performed:</p> <pre><code>mkdir /home/dokku/node-js-app/nginx.conf.d/\necho 'client_header_timeout 50s;' &gt; /home/dokku/node-js-app/nginx.conf.d/timeout.conf\nchown dokku:dokku /home/dokku/node-js-app/nginx.conf.d/upload.conf\nservice nginx reload\n</code></pre> <p>The example above uses additional configuration files directly on the Dokku host. Unlike the <code>nginx.conf.sigil</code> file, these additional files will not be copied over from your application repo, and thus need to be placed in the <code>/home/dokku/node-js-app/nginx.conf.d/</code> directory manually.</p> <p>For PHP Buildpack users, you will also need to provide a <code>Procfile</code> and an accompanying <code>nginx.conf</code> file to customize the nginx config within the container. The following are example contents for your <code>Procfile</code></p> <pre><code>web: vendor/bin/heroku-php-nginx -C nginx.conf -i php.ini php/\n</code></pre> <p>Your <code>nginx.conf</code> file - not to be confused with Dokku's <code>nginx.conf.sigil</code> - would also need to be configured as shown in this example:</p> <pre><code>client_header_timeout 50s;\nlocation / {\n    index index.php;\n    try_files $uri $uri/ /index.php$is_args$args;\n}\n</code></pre> <p>Please adjust the <code>Procfile</code> and <code>nginx.conf</code> file as appropriate.</p>"},{"location":"networking/proxies/nginx/#custom-error-pages","title":"Custom Error Pages","text":"<p>By default, Dokku provides custom error pages for the following three categories of errors:</p> <ul> <li>4xx: For all non-404 errors with a 4xx response code.</li> <li>404: For \"404 Not Found\" errors.</li> <li>5xx: For all 5xx error responses</li> </ul> <p>These are provided as an alternative to the generic Nginx error page, are shared for all applications, and their contents are located on disk at <code>/var/lib/dokku/data/nginx-vhosts/dokku-errors</code>. To customize them for a specific app, create a custom <code>nginx.conf.sigil</code> as described above and change the paths to point elsewhere.</p>"},{"location":"networking/proxies/nginx/#default-site","title":"Default site","text":"<p>By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website.</p> <p>Warning</p> <p>some versions of Nginx may create a default site when installed. This site is simply a static page which says \"Welcome to Nginx\", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:</p> <pre><code>rm /etc/nginx/sites-enabled/default\ndokku nginx:stop\ndokku nginx:start\n</code></pre> <p>If services should only be accessed via their domain name, you may want to disable the default site by adding the following configuration to the global nginx configuration.</p> <p>Create the file at <code>/etc/nginx/conf.d/00-default-vhost.conf</code>:</p> <pre><code>server {\n    listen 80 default_server;\n    listen [::]:80 default_server;\n\n    # If services hosted by dokku are available via HTTPS, it is recommended\n    # to also uncomment the following section.\n    #\n    # Please note that in order to let this work, you need an SSL certificate. However\n    # it does not need to be valid. Users of Debian-based distributions can install the\n    # `ssl-cert` package with `sudo apt install ssl-cert` to automatically generate\n    # a self-signed certificate that is stored at `/etc/ssl/certs/ssl-cert-snakeoil.pem`.\n    #\n    #listen 443 ssl;\n    #listen [::]:443 ssl;\n    #ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;\n    #ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;\n\n    server_name _;\n    access_log off;\n    return 444;\n}\n</code></pre> <p>Make sure to reload nginx after creating this file by running <code>systemctl reload nginx.service</code>.</p> <p>This will catch all unknown HOST header values and close the connection without responding. You can replace the <code>return 444;</code> with <code>return 410;</code> which will cause nginx to respond with an error page.</p> <p>The configuration file must be loaded before <code>/etc/nginx/conf.d/dokku.conf</code>, so it can not be arranged as a vhost in <code>/etc/nginx/sites-enabled</code> that is only processed afterwards.</p> <p>Alternatively, you may push an app to your Dokku host with a name like \"00-default\". As long as it lists first in <code>ls /home/dokku/*/nginx.conf | head</code>, it will be used as the default nginx vhost.</p>"},{"location":"networking/proxies/nginx/#other","title":"Other","text":""},{"location":"networking/proxies/nginx/#domains-plugin","title":"Domains plugin","text":"<p>See the domain configuration documentation for more information on how to configure domains for your app.</p>"},{"location":"networking/proxies/nginx/#customizing-hostnames","title":"Customizing hostnames","text":"<p>See the customizing hostnames documentation for more information on how to configure domains for your app.</p>"},{"location":"networking/proxies/nginx/#disabling-vhosts","title":"Disabling VHOSTS","text":"<p>See the disabling vhosts documentation for more information on how to disable domain usage for your app.</p>"},{"location":"networking/proxies/nginx/#ssl-configuration","title":"SSL Configuration","text":"<p>See the ssl documentation for more information on how to configure SSL certificates for your application.</p>"},{"location":"networking/proxies/nginx/#disabling-nginx","title":"Disabling Nginx","text":"<p>See the proxy documentation for more information on how to disable nginx as the proxy implementation for your app.</p>"},{"location":"networking/proxies/nginx/#managing-proxy-port-mappings","title":"Managing Proxy Port mappings","text":"<p>See the ports documentation for more information on how to manage ports proxied for your app.</p>"},{"location":"networking/proxies/nginx/#regenerating-nginx-config","title":"Regenerating nginx config","text":"<p>See the proxy documentation for more information on how to rebuild the nginx proxy configuration for your app.</p>"},{"location":"networking/proxies/openresty/","title":"OpenResty Proxy","text":"<p>New</p> <p>Introduced in 0.31.0</p> <p>Dokku can provide integration with the OpenResty proxy service by utilizing the Docker label-based integration implemented by openresty-docker-proxy.</p> <pre><code>openresty:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a openresty report for one or more apps\nopenresty:logs [--num num] [--tail]          # Display openresty log output\nopenresty:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an openresty property for an app\nopenresty:show-config &lt;app&gt;                  # Display openresty compose config\nopenresty:start                              # Starts the openresty server\nopenresty:stop                               # Stops the openresty server\n</code></pre>"},{"location":"networking/proxies/openresty/#requirements","title":"Requirements","text":"<p>Using the <code>openresty</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/openresty/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty.</p> <p>The OpenResty plugin has specific rules for routing requests:</p> <ul> <li>OpenResty integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While OpenResty will respect labels associated with other containers, only <code>web</code> containers have OpenResty labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported at this time.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/openresty/#switching-to-openresty","title":"Switching to OpenResty","text":"<p>To use the OpenResty plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app openresty\n</code></pre> <p>This will enable the docker label-based OpenResty integration. All future deploys will inject the correct labels for OpenResty to read and route requests to containers. Due to the docker label-based integration used by OpenResty, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/openresty/#starting-openresty-container","title":"Starting OpenResty container","text":"<p>OpenResty can be started via the <code>openresty:start</code> command. This will start a OpenResty container via the <code>docker compose up</code> command.</p> <pre><code>dokku openresty:start\n</code></pre>"},{"location":"networking/proxies/openresty/#stopping-the-openresty-container","title":"Stopping the OpenResty container","text":"<p>OpenResty may be stopped via the <code>openresty:stop</code> command.</p> <pre><code>dokku openresty:stop\n</code></pre> <p>The OpenResty container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/openresty/#showing-the-openresty-compose-config","title":"Showing the OpenResty compose config","text":"<p>For debugging purposes, it may be useful to show the OpenResty compose config. This can be achieved via the <code>openresty:show-config</code> command.</p> <pre><code>dokku openresty:show-config\n</code></pre>"},{"location":"networking/proxies/openresty/#customizing-the-openresty-container-image","title":"Customizing the OpenResty container image","text":"<p>While the default OpenResty image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku openresty:set --global image dokku/openresty-docker-proxy:0.5.6\n</code></pre>"},{"location":"networking/proxies/openresty/#checking-the-openresty-containers-logs","title":"Checking the OpenResty container's logs","text":"<p>It may be necessary to check the OpenResty container's logs to ensure that OpenResty is operating as expected. This can be performed with the <code>openresty:logs</code> command.</p> <pre><code>dokku openresty:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku openresty:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the openresty container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/openresty/#customizing-openresty-settings-for-an-app","title":"Customizing Openresty Settings for an app","text":""},{"location":"networking/proxies/openresty/#openresty-properties","title":"OpenResty Properties","text":"<p>The OpenResty plugin supports all properties supported by the <code>nginx:set</code> command via <code>openresty:set</code>. At this time, please consult the nginx documentation for more information on what properties are available.</p> <p>Please note that the oldest running container will be used for OpenResty configuration, and thus newer config may not apply until older app containers are retired during/after a deploy, depending on your zero-downtime settings.</p>"},{"location":"networking/proxies/openresty/#custom-openresty-templates","title":"Custom OpenResty Templates","text":"<p>At this time, the OpenResty plugin does not allow complete customization of the template used to manage an app's vhost. Apps will use a template provided by the OpenResty container to proxy requests. See the next section for documentation on how to configure portions of the template.</p>"},{"location":"networking/proxies/openresty/#injecting-custom-snippets-into-the-openresty-config","title":"Injecting custom snippets into the OpenResty config","text":"<p>The OpenResty plugin allows users to specify templates in their repository for auto-injection into the OpenResty config. Please note that this configuration should be validated prior to deployment or may cause outages in your OpenResty proxy layer.</p> <p>The following folders within an app repository may have <code>*.conf</code> files that will be automatically injected into the OpenResty config.</p> <ul> <li><code>openresty/http-includes/</code>: Injected in the <code>server</code> block serving http(s) requests for the app.</li> <li><code>openresty/http-location-includes/</code>: Injected in the <code>location</code> block that proxies to the app in the app's respective <code>server</code> block.</li> </ul>"},{"location":"networking/proxies/openresty/#ssl-configuration","title":"SSL Configuration","text":"<p>The OpenResty plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/openresty/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku openresty:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/openresty/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku openresty:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/openresty/#displaying-openresty-reports-for-an-app","title":"Displaying OpenResty reports for an app","text":"<p>You can get a report about the app's OpenResty config using the <code>openresty:report</code> command:</p> ShellOutput <pre><code>dokku openresty:report\n</code></pre> <pre><code>=====&gt; node-js-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n=====&gt; python-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n=====&gt; ruby-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku openresty:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku openresty:report node-js-app --openresty-letsencrypt-email\n</code></pre>"},{"location":"networking/proxies/traefik/","title":"Traefik Proxy","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>Dokku provides integration with the Traefik proxy service by utilizing the Docker label-based integration implemented by Traefik.</p> <pre><code>traefik:report [&lt;app&gt;] [&lt;flag&gt;]          # Displays a traefik report for one or more apps\ntraefik:logs [--num num] [--tail]        # Display traefik log output\ntraefik:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)   # Set or clear an traefik property for an app\ntraefik:show-config &lt;app&gt;                # Display traefik compose config\ntraefik:start                            # Starts the traefik server\ntraefik:stop                             # Stops the traefik server\n</code></pre>"},{"location":"networking/proxies/traefik/#requirements","title":"Requirements","text":"<p>Using the <code>traefik</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/traefik/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik.</p> <p>The Traefik plugin has specific rules for routing requests:</p> <ul> <li>Traefik integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While Traefik will respect labels associated with other containers, only <code>web</code> containers have Traefik labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported.</li> <li>If no <code>http:80</code> mapping is found, the first <code>http</code> port mapping is used for http requests.</li> <li>If no <code>https:443</code> mapping is found, the first <code>https</code> port mapping is used for https requests.</li> <li>If no <code>https</code> mapping is found, the container port from <code>http:80</code> will be used for https requests.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/traefik/#switching-to-traefik","title":"Switching to Traefik","text":"<p>To use the Traefik plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app traefik\n</code></pre> <p>This will enable the docker label-based Traefik integration. All future deploys will inject the correct labels for Traefik to read and route requests to containers. Due to the docker label-based integration used by Traefik, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/traefik/#starting-traefik-container","title":"Starting Traefik container","text":"<p>Traefik can be started via the <code>traefik:start</code> command. This will start a Traefik container via the <code>docker compose up</code> command.</p> <pre><code>dokku traefik:start\n</code></pre>"},{"location":"networking/proxies/traefik/#stopping-the-traefik-container","title":"Stopping the Traefik container","text":"<p>Traefik may be stopped via the <code>traefik:stop</code> command.</p> <pre><code>dokku traefik:stop\n</code></pre> <p>The Traefik container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/traefik/#showing-the-traefik-compose-config","title":"Showing the Traefik compose config","text":"<p>For debugging purposes, it may be useful to show the Traefik compose config. This can be achieved via the <code>traefik:show-config</code> command.</p> <pre><code>dokku traefik:show-config\n</code></pre>"},{"location":"networking/proxies/traefik/#customizing-the-traefik-container-image","title":"Customizing the Traefik container image","text":"<p>While the default Traefik image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global image traefik:v2.8\n</code></pre>"},{"location":"networking/proxies/traefik/#checking-the-traefik-containers-logs","title":"Checking the Traefik container's logs","text":"<p>It may be necessary to check the Traefik container's logs to ensure that Traefik is operating as expected. This can be performed with the <code>traefik:logs</code> command.</p> <pre><code>dokku traefik:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku traefik:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the traefik container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/traefik/#changing-the-traefik-log-level","title":"Changing the Traefik log level","text":"<p>Traefik log output is set to <code>ERROR</code> by default. It may be changed by setting the <code>log-level</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global log-level DEBUG\n</code></pre> <p>After modifying, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#setting-rule-priority","title":"Setting rule priority","text":"<p>By default, app deployments will result in the newer traefik rules using a higher priority in order to have any newer rules respected by Traefik. Rule priorities will always increase according to the current unix timestamp. The priority may be fixed by setting the app-level <code>priority</code> property:</p> <pre><code>dokku traefik:set node-js-app priority 12345\n</code></pre> <p>After modifying, the app container will need to be recreated via a <code>ps:rebuild</code> or an app deployment.</p>"},{"location":"networking/proxies/traefik/#ssl-configuration","title":"SSL Configuration","text":"<p>The traefik plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/traefik/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, apps will need to be rebuilt and the Traefik container will need to be restarted. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/traefik/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the Traefik container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/traefik/#api-access","title":"API Access","text":"<p>Traefik exposes an API and Dashboard, which Dokku disables by default for security reasons. It can be exposed and customized as described below.</p>"},{"location":"networking/proxies/traefik/#enabling-the-api","title":"Enabling the api","text":"<p>Warning</p> <p>Users enabling the dashboard should also enable api basic auth.</p> <p>By default, the api is disabled. To enable, set the <code>api</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global api true\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#enabling-the-dashboard","title":"Enabling the dashboard","text":"<p>Warning</p> <p>Users enabling the dashboard should also enable api basic auth.</p> <p>By default, the dashboard is disabled. To enable, set the <code>dashboard</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global dashboard true\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#enabling-api-basic-auth","title":"Enabling api basic auth","text":"<p>Users enabling either the api or dashboard are encouraged to enable basic auth. This will apply only to the api/dashboard, and not to apps. To enable, set the <code>basic-auth-username</code> and <code>basic-auth-password</code> properties with the <code>--global</code> flag:. Both must be set or basic auth will not be enabled.</p> <pre><code>dokku traefik:set --global basic-auth-username username\ndokku traefik:set --global basic-auth-password password\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#customizing-the-api-hostname","title":"Customizing the api hostname","text":"<p>The hostname used for the api and dashboard is set to <code>traefik.dokku.me</code> by default. It can be customized by setting the <code>api-vhost</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global api-vhost lb.dokku.me\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#displaying-traefik-reports-for-an-app","title":"Displaying Traefik reports for an app","text":"<p>You can get a report about the app's Traefik config using the <code>traefik:report</code> command:</p> ShellOutput <pre><code>dokku traefik:report\n</code></pre> <pre><code>=====&gt; node-js-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n=====&gt; python-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n=====&gt; ruby-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku traefik:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku traefik:report node-js-app --traefik-api-enabled\n</code></pre>"},{"location":"processes/entering-containers/","title":"Entering containers","text":"<p>New</p> <p>Introduced in 0.4.0</p> <pre><code>enter &lt;app&gt;  [&lt;container-type&gt; || --container-id &lt;container-id&gt;]  # Connect to a specific app container\n</code></pre>"},{"location":"processes/entering-containers/#usage","title":"Usage","text":"<p>The <code>enter</code> command can be used to enter a running container. The following variations of the command exist:</p> <pre><code># enter the web process\ndokku enter node-js-app web\n\n# enter the first web process\ndokku enter node-js-app web.1\n\n# enter a process for an app by container ID\ndokku enter node-js-app --container-id ID\n</code></pre> <p>The <code>container-type</code> argument can be one either:</p> <ul> <li>If your app has a <code>Procfile</code>, the name of a process type in your <code>Procfile</code>.</li> <li>If your app has no <code>Procfile</code>, the word <code>web</code>.</li> </ul> <p>If the specified process type is scaled up to more than one container, then the first container will be automatically selected. this can be overriden by specifying an integer index denoting the desired container, where the first container's index is <code>1</code>.</p> <p>Additionally, the <code>enter</code> command can be executed with no <code>&lt;container-type&gt;</code>. If only a single <code>&lt;container-type&gt;</code> is defined in the app's Procfile, executing <code>enter</code> will drop the terminal into the only running container. This behavior is not supported when specifying a custom command; as described below.</p> <p>By default, <code>dokku enter</code> will run a <code>/bin/bash</code>, but can also be used to run custom commands:</p> <pre><code># just echo hi\ndokku enter node-js-app web echo hi\n\n# run a long-running command, as one might for a cron task\ndokku enter node-js-app web python script/background-worker.py\n</code></pre>"},{"location":"processes/one-off-tasks/","title":"One-off Tasks","text":"<pre><code>run [-e|--env KEY=VALUE] [--no-tty] &lt;app&gt; &lt;cmd&gt;              # Run a command in a new container using the current app image\nrun:detached [-e|-env KEY=VALUE] [--no-tty] &lt;app&gt; &lt;cmd&gt;      # Run a command in a new detached container using the current app image\nrun:list [--format json|stdout] [&lt;app&gt;]                      # List all run containers for an app\nrun:logs &lt;app|--container CONTAINER&gt; [-h] [-t] [-n num] [-q] # Display recent log output for run containers\nrun:stop &lt;app|--container CONTAINER&gt;                         # Stops all run containers for an app or a specified run container\n</code></pre> <p>Sometimes it is necessary to run a one-off command under an app. Dokku makes it easy to run a fresh container via the <code>run</code> command.</p>"},{"location":"processes/one-off-tasks/#usage","title":"Usage","text":""},{"location":"processes/one-off-tasks/#running-a-one-off-command","title":"Running a one-off command","text":"<p>The <code>run</code> command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container.  The container image will be the same container image as was used to start the currently deployed app.</p> <p>New</p> <p>Introduced in 0.25.0, this container will be removed after the process exits.</p> <pre><code># runs `ls -lah` in the `/app` directory of the app `node-js-app`\ndokku run node-js-app ls -lah\n\n# optionally, run can be passed custom environment variables\ndokku run --env \"NODE_ENV=development\" --env \"PATH=/custom/path\" node-js-app npm run mytask\n</code></pre> <p>One off containers are removed at the end of process execution.</p>"},{"location":"processes/one-off-tasks/#running-procfile-commands","title":"Running Procfile commands","text":"<p>The <code>run</code> command can also be used to run a command defined in the app <code>Procfile</code>:</p> <pre><code>console: bundle exec racksh\n</code></pre> <pre><code># runs `bundle exec racksh` in the `/app` directory of the app `my-app`\ndokku run my-app console\n</code></pre>"},{"location":"processes/one-off-tasks/#specifying-container-labels","title":"Specifying container labels","text":"<p>Containers may have specific labels attached. In order to avoid issues with dokku internals, do not use any labels beginning with either <code>com.dokku</code> or <code>org.label-schema</code>.</p> <pre><code>dokku --label=com.example.test-label=value run node-js-app ls -lah\n</code></pre>"},{"location":"processes/one-off-tasks/#disabling-tty","title":"Disabling TTY","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>One-off containers default to interactive mode where possible. To disable this behavior, specify the <code>--no-tty</code> flag:</p> <pre><code>dokku run --no-tty node-js-app ls -lah\n</code></pre>"},{"location":"processes/one-off-tasks/#running-a-detached-container","title":"Running a detached container","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>Finally, a container can be run in \"detached\" mode via the <code>run:detached</code> Dokku command. Running a process in detached mode will immediately return a <code>CONTAINER_ID</code>. Detached containers are run without a tty and are also removed at the end of process execution.</p> <pre><code>dokku run:detached node-js-app ls -lah\n# returns the ID of the new container\n</code></pre>"},{"location":"processes/one-off-tasks/#displaying-one-off-container-logs","title":"Displaying one-off container logs","text":"<p>You can easily get logs of all one-off containers for an app using the <code>logs</code> command:</p> <pre><code>dokku run:logs node-js-app\n</code></pre> <p>Logs are pulled via integration with the scheduler for the specified application via \"live tailing\". As such, logs from previously running deployments are usually not available. Users that desire to see logs from previous deployments for debugging purposes should persist those logs to external services. Please see Dokku's vector integration for more information on how to persist logs across deployments to ship logs to another service or a third-party platform.</p>"},{"location":"processes/one-off-tasks/#behavioral-modifiers","title":"Behavioral modifiers","text":"<p>Dokku also supports certain command-line arguments that augment the <code>run:log</code> command's behavior.</p> <pre><code>--container NAME     # the name of a specific container to show logs for\n-n, --num NUM        # the number of lines to display\n-t, --tail           # continually stream logs\n-q, --quiet          # display raw logs without colors, time and names\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku run:logs -t --container node-js-app.run.1234\n</code></pre> <p>The above command will show logs continually from the <code>node-js-app.run.1234</code> one-off run process.</p>"},{"location":"processes/one-off-tasks/#listing-one-off-containers","title":"Listing one-off containers","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>One-off containers for a given app can be listed via the <code>run:list</code> command:</p> ShellOutput <pre><code>dokku run:list node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app run containers\nNAMES                   COMMAND            CREATED\nnode-js-app.run.28689   \"/exec sleep 15\"   2 seconds ago\n</code></pre> <p>Info</p> <p>The <code>COMMAND</code> displayed will be what Docker executes and may not exactly match the command specified by a <code>dokku run</code> command.</p> <p>The output can also be shown in json format:</p> ShellOutput <pre><code>dokku run:list node-js-app --format json\n</code></pre> <pre><code>[\n  {\n    \"name\": \"node-js-app.run.28689\",\n    \"state\": \"running\",\n    \"command\": \"\\\"/exec 'sleep 15'\\\"\",\n    \"created_at\": \"2022-08-03 05:47:44 +0000 UTC\"\n  }\n]\n</code></pre>"},{"location":"processes/one-off-tasks/#stopping-a-one-off-container","title":"Stopping a one-off container","text":"<p>New</p> <p>Introduced in 0.29.0</p> <p>Run containers for an app can be stopped via the <code>run:stop</code> command. The output will be the container id.</p> ShellOutput <pre><code># start a container\n# the output will be something like: node-js-app.run.2313\ndokku run node-js-app sleep 300\n\n# stop the container\ndokku run:stop --container node-js-app.run.2313\n</code></pre> <pre><code>node-js-app.run.2313\n</code></pre> <p>All containers for a given app can be stopped by specifying the app name.</p> ShellOutput <pre><code>dokku run:stop node-js-app\n</code></pre> <pre><code>node-js-app.run.2313\nnode-js-app.run.574\n</code></pre>"},{"location":"processes/process-management/","title":"Process Management","text":"<p>New</p> <p>Introduced in 0.3.14, Enhanced in 0.7.0</p> <pre><code>ps:inspect &lt;app&gt;                                                  # Displays a sanitized version of docker inspect for an app\nps:rebuild [--parallel count] [--all|&lt;app&gt;]                       # Rebuilds an app from source\nps:report [&lt;app&gt;] [&lt;flag&gt;]                                        # Displays a process report for one or more apps\nps:restart [--parallel count] [--all|&lt;app&gt;]  [&lt;process-name&gt;]     # Restart an app\nps:restore [&lt;app&gt;]                                                # Start previously running apps e.g. after reboot\nps:scale [--skip-deploy] &lt;app&gt; &lt;proc&gt;=&lt;count&gt; [&lt;proc&gt;=&lt;count&gt;...] # Get/Set how many instances of a given process to run\nps:set &lt;app&gt; &lt;key&gt; &lt;value&gt;                                        # Set or clear a ps property for an app\nps:start [--parallel count] [--all|&lt;app&gt;]                         # Start an app\nps:stop [--parallel count] [--all|&lt;app&gt;]                          # Stop an app\n</code></pre>"},{"location":"processes/process-management/#usage","title":"Usage","text":""},{"location":"processes/process-management/#inspecting-app-containers","title":"Inspecting app containers","text":"<p>New</p> <p>Introduced in 0.13.0</p> <p>A common administrative task to perform is calling <code>docker inspect</code> on the containers that are running for an app. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the <code>ps:inspect</code> command:</p> <pre><code>dokku ps:inspect node-js-app\n</code></pre> <p>This command will gather all the running container IDs for your app and call <code>docker inspect</code>, sanitizing the output data so it can be copy-pasted elsewhere safely.</p>"},{"location":"processes/process-management/#rebuilding-apps","title":"Rebuilding apps","text":"<p>It may be useful to rebuild an app at will, such as for commands that do not rebuild an app or when skipping a rebuild after setting multiple config values. For these use cases, the <code>ps:rebuild</code> function can be used.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>All apps may be rebuilt by using the <code>--all</code> flag.</p> <pre><code>dokku ps:rebuild --all\n</code></pre> <p>By default, rebuilding all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:rebuild --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:rebuild --all --parallel -1\n</code></pre> <p>A missing linked container will result in failure to boot apps. Services should all be started for apps being rebuilt.</p>"},{"location":"processes/process-management/#restarting-apps","title":"Restarting apps","text":"<p>An app may be restarted using the <code>ps:restart</code> command.</p> <pre><code>dokku ps:restart node-js-app\n</code></pre> <p>A single process type - such as <code>web</code> or <code>worker</code> - may also be specified. This does not support specifying a given instance of a process type, and only supports restarting all instances of that process type.</p> <pre><code>dokku ps:restart node-js-app web\n</code></pre> <p>All apps may be restarted by using the <code>--all</code> flag. This flag is incompatible with specifying a process type.</p> <pre><code>dokku ps:restart --all\n</code></pre> <p>By default, restarting all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:restart --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:restart --all --parallel -1\n</code></pre> <p>A missing linked container will result in failure to boot apps. Services should all be started for apps being rebuilt.</p>"},{"location":"processes/process-management/#displaying-existing-scale-properties","title":"Displaying existing scale properties","text":"<p>Issuing the <code>ps:scale</code> command with no arguments will output the current scaling properties for an app.</p> ShellOutput <pre><code>dokku ps:scale node-js-app\n</code></pre> <pre><code>-----&gt; Scaling for python\nproctype: qty\n--------: ---\nweb:  1\n</code></pre>"},{"location":"processes/process-management/#defining-processes","title":"Defining Processes","text":""},{"location":"processes/process-management/#procfile","title":"Procfile","text":"<p>Note</p> <p>Dokku supports the Procfile format as defined in this document under \"Strict Mode\" parsing rules.</p> <p>Apps can define processes to run by using a <code>Procfile</code>. A <code>Procfile</code> is a simple text file that can be used to specify multiple commands, each of which is subject to process scaling. In the case where the built image sets a default command to run - either through usage of <code>CMD</code> for Dockerfile-based builds, a default process for buildpack-based builds, or any other method for the builder in use - the <code>Procfile</code> will take precedence.</p> <p>If the file exists, it should not be empty, as doing so may result in a failed deploy.</p> <p>The syntax for declaring a <code>Procfile</code> is as follows. Note that the format is one process type per line, with no duplicate process types.</p> <pre><code>&lt;process type&gt;: &lt;command&gt;\n</code></pre> <p>If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types:</p> <pre><code>worker:           env QUEUE=* bundle exec rake resque:work\nimportantworker:  env QUEUE=important bundle exec rake resque:work\n</code></pre> <p>If the app build declares an <code>ENTRYPOINT</code>, the command defined in the <code>Procfile</code> is passed as an argument to that entrypoint. This is the case for all Dockerfile-based, Docker Image, and Cloud Native Buildpack deployments.</p> <p>The <code>web</code> process type holds some significance in that it is the only process type that is automatically scaled to <code>1</code> on the initial application deploy. See the web process scaling documentation for more details around scaling individual processes.</p> <p>See the Procfile location documentation for more information on where to place your <code>Procfile</code> file.</p>"},{"location":"processes/process-management/#the-web-process","title":"The <code>web</code> process","text":"<p>For initial app deploys, Dokku will default to starting a single <code>web</code> process for each app. This process may be defined within the <code>Procfile</code> or as the <code>CMD</code> (for Dockerfile or Docker image deploys). Scaling of the <code>web</code> process - and all other processes - may be managed via <code>ps:scale</code> or the <code>formation</code> key in the <code>app.json</code> file either before or after the initial deploy.</p> <p>There are also a few other exceptions for the <code>web</code> process.</p> <ul> <li>By default, the built-in nginx proxy implementation only proxies the <code>web</code> process (others may be handled via a custom <code>nginx.conf.sigil</code>).<ul> <li>See the nginx request proxying documentation for more information on how nginx handles proxied requests.</li> </ul> </li> <li>Only the <code>web</code> process may be bound to an external port.</li> </ul>"},{"location":"processes/process-management/#the-release-process","title":"The <code>release</code> process","text":"<p>The <code>Procfile</code> also supports a special <code>release</code> command which acts in a similar way to the Heroku Release Phase. See the Release deployment task documentation for more information on how Dokku handles this process type.</p>"},{"location":"processes/process-management/#changing-the-procfile-location","title":"Changing the <code>Procfile</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>Procfile</code> file to use for a given app. This can be done via the <code>ps:set</code> command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no <code>Procfile</code>.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>Procfile</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>Procfile</code> extracted directly from the source code. Both cases will respect the configured <code>procfile-path</code> property value.</p> <pre><code>dokku ps:set node-js-app procfile-path .dokku/Procfile\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku ps:set node-js-app procfile-path\n</code></pre> <p>The <code>procfile-path</code> property can also be set globally. The global default is <code>Procfile</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku ps:set --global procfile-path global-Procfile\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku ps:set --global procfile-path\n</code></pre>"},{"location":"processes/process-management/#scaling-apps","title":"Scaling apps","text":""},{"location":"processes/process-management/#via-cli","title":"Via CLI","text":"<p>Info</p> <p>This functionality is disabled if the formation is managed via the <code>formation</code> key of <code>app.json</code>.</p> <p>Dokku can also manage scaling itself via the <code>ps:scale</code> command. This command can be used to scale multiple process types at the same time.</p> <pre><code>dokku ps:scale node-js-app web=1\n</code></pre> <p>Multiple process types can be scaled at once:</p> <pre><code>dokku ps:scale node-js-app web=1 worker=1\n</code></pre> <p>If desired, the corresponding deploy will be skipped by using the <code>--skip-deploy</code> flag:</p> <pre><code>dokku ps:scale --skip-deploy node-js-app web=1\n</code></pre>"},{"location":"processes/process-management/#manually-managing-process-scaling","title":"Manually managing process scaling","text":"<p>Info</p> <p>Using a <code>formation</code> key in an <code>app.json</code> file with any <code>quantity</code> specified disables the ability to use <code>ps:scale</code> for scaling. All processes not specified in the <code>app.json</code> will have their process count set to zero.</p> <p>Users can also configure scaling within the codebase itself to manage process scaling. The <code>formation</code> key should be specified as follows in the <code>app.json</code> file:</p> <pre><code>{\n  \"formation\": {\n    \"web\": {\n      \"quantity\": 1\n    },\n    \"worker\": {\n      \"quantity\": 4\n    }\n  }\n}\n</code></pre> <p>Removing the <code>formation</code> key or removing the <code>app.json</code> file from your repository will result in Dokku respecting the <code>ps:scale</code> command for setting scale values. The values set via the <code>app.json</code> file from a previous deploy will be respected.</p> <p>See the app.json location documentation for more information on where to place your <code>app.json</code> file.</p>"},{"location":"processes/process-management/#stopping-apps","title":"Stopping apps","text":"<p>Deployed apps can be stopped using the <code>ps:stop</code> command. This turns off all running containers for an app, and will result in a 502 Bad Gateway response for the default nginx proxy implementation.</p> <pre><code>dokku ps:stop node-js-app\n</code></pre> <p>All apps may be stopped by using the <code>--all</code> flag.</p> <pre><code>dokku ps:stop --all\n</code></pre> <p>By default, stopping all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:stop --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:stop --all --parallel -1\n</code></pre>"},{"location":"processes/process-management/#starting-apps","title":"Starting apps","text":"<p>All stopped containers can be started using the <code>ps:start</code> command. This is similar to running <code>ps:restart</code>, except no action will be taken if the app containers are running.</p> <pre><code>dokku ps:start node-js-app\n</code></pre> <p>All apps may be started by using the <code>--all</code> flag.</p> <pre><code>dokku ps:start --all\n</code></pre> <p>By default, starting all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:start --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:start --all --parallel -1\n</code></pre>"},{"location":"processes/process-management/#restart-policies","title":"Restart policies","text":"<p>New</p> <p>Introduced in 0.7.0, Command Changed in 0.22.0</p> <p>By default, Dokku will automatically restart containers that exit with a non-zero status up to 10 times via the on-failure Docker restart policy.</p>"},{"location":"processes/process-management/#setting-the-restart-policy","title":"Setting the restart policy","text":"<p>Info</p> <p>A change in the restart policy must be followed by a <code>ps:rebuild</code> call.</p> <p>You can configure this via the <code>ps:set</code> command:</p> <pre><code># always restart an exited container\ndokku ps:set node-js-app restart-policy always\n\n# never restart an exited container\ndokku ps:set node-js-app restart-policy no\n\n# only restart it on Docker restart if it was not manually stopped\ndokku ps:set node-js-app restart-policy unless-stopped\n\n# restart only on non-zero exit status\ndokku ps:set node-js-app restart-policy on-failure\n\n# restart only on non-zero exit status up to 20 times\ndokku ps:set node-js-app restart-policy on-failure:20\n</code></pre> <p>Restart policies have no bearing on server reboot, and Dokku will always attempt to restart your apps at that point unless they were manually stopped.</p> <p>Dokku also runs <code>dokku-event-listener</code> in the background via the system's init service. This monitors container state, performing the following actions:</p> <ul> <li>If a web process restarts and it's container IP address changes, the app's proxy configuration will be rebuilt.</li> <li>If a process within an app exceeds the restart count, the app will be rebuilt.</li> </ul>"},{"location":"processes/process-management/#displaying-reports-for-an-app","title":"Displaying reports for an app","text":"<p>New</p> <p>Introduced in 0.12.0</p> <p>You can get a report about the deployed apps using the <code>ps:report</code> command:</p> ShellOutput <pre><code>dokku ps:report\n</code></pre> <pre><code>=====&gt; node-js-app ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps computed procfile path:     Procfile2\n       Ps global procfile path:       Procfile\n       Ps restart policy:             on-failure:10\n       Ps procfile path:              Procfile2\n       Restore:                       true\n       Running:                       false\n=====&gt; python-sample ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps computed procfile path:     Procfile\n       Ps global procfile path:       Procfile\n       Ps restart policy:             on-failure:10\n       Ps procfile path:\n       Restore:                       true\n       Running:                       false\n=====&gt; ruby-sample ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps computed procfile path:     Procfile\n       Ps global procfile path:       Procfile\n       Ps restart policy:             on-failure:10\n       Ps procfile path:\n       Restore:                       true\n       Running:                       false\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku ps:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps restart policy:             on-failure:10\n       Restore:                       true\n       Running:                       false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku ps:report node-js-app --deployed\n</code></pre>"},{"location":"processes/process-management/#restoring-apps-after-a-server-reboot","title":"Restoring apps after a server reboot","text":"<p>When a server reboots or Docker is restarted/upgraded, Docker may or may not start old app containers automatically, and may in some cases re-assign container IP addresses. To combat this issue, Dokku uses an init process that triggers <code>dokku ps:restore</code> after the Docker daemon is detected as starting. When triggered, the <code>dokku ps:restore</code> command will serially (one by one) run the following for each:</p> <ul> <li>Start all linked services.</li> <li>Clear generated proxy configuration files.</li> <li>Start the app if it has not been manually stopped.<ul> <li>If the app containers still exist, they will be started and the generated proxy configuration files will be rebuilt.</li> <li>If any of the app containers are missing, the entire app will be rebuilt.</li> </ul> </li> </ul> <p>During this time, requests may route to the incorrect app if the assigned IPs correspond to those for other apps. While dokku makes all efforts to avoid this, there may be a few minutes where urls may route to the wrong app. To avoid this, either use a custom proxy plugin or wait a few minutes until the restoration process is complete.</p>"},{"location":"processes/scheduled-cron-tasks/","title":"Scheduled Cron Tasks","text":"<p>New</p> <p>Introduced in 0.23.0</p> <pre><code>cron:list &lt;app&gt; [--format json|stdout] # List scheduled cron tasks for an app\ncron:report [&lt;app&gt;] [&lt;flag&gt;]           # Display report about an app\ncron:run &lt;app&gt; &lt;cron_id&gt; [--detach]    # Run a cron task on the fly\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#usage","title":"Usage","text":""},{"location":"processes/scheduled-cron-tasks/#dokku-managed-cron","title":"Dokku Managed Cron","text":"<p>Dokku automates scheduled <code>dokku run</code> commands via it's <code>app.json</code> cron integration.</p>"},{"location":"processes/scheduled-cron-tasks/#specifying-commands","title":"Specifying commands","text":"<p>The <code>app.json</code> file for a given app can define a special <code>cron</code> key that contains a list of commands to run on given schedules. The following is a simple example <code>app.json</code> that effectively runs the command <code>dokku run $APP npm run send-email</code> once a day:</p> <pre><code>{\n  \"cron\": [\n    {\n      \"command\": \"npm run send-email\",\n      \"schedule\": \"@daily\"\n    }\n  ]\n}\n</code></pre> <p>A cron entry takes the following properties:</p> <ul> <li><code>command</code>: A command to be run within the built app image. Specified commands can also be <code>Procfile</code> entries.</li> <li><code>schedule</code>: A cron-compatible scheduling definition upon which to run the command. Seconds are generally not supported.</li> </ul> <p>Zero or more cron commands can be specified per app. Cron entries are validated after the build artifact is created but before the app is deployed, and the cron schedule is updated during the post-deploy phase.</p> <p>See the app.json location documentation for more information on where to place your <code>app.json</code> file.</p>"},{"location":"processes/scheduled-cron-tasks/#task-environment","title":"Task Environment","text":"<p>When running scheduled cron tasks, there are a few items to be aware of:</p> <ul> <li>Scheduled cron tasks are performed within the app environment available at runtime. If the app image does not exist, the command may fail to execute.</li> <li>Schedules are performed on the hosting server's timezone, which is typically UTC.</li> <li>At this time, only the <code>PATH</code> and <code>SHELL</code> environment variables are specified in the cron template.<ul> <li>A <code>MAILTO</code> value can be set via the <code>cron:set</code> command.</li> </ul> </li> <li>Each scheduled task is executed within a one-off <code>run</code> container, and thus inherit any docker-options specified for <code>run</code> containers. Resources are never shared between scheduled tasks.</li> <li>Scheduled cron tasks are supported on a per-scheduler basis, and are currently only implemented by the <code>docker-local</code> scheduler.</li> <li>Tasks for all apps managed by the <code>docker-local</code> scheduler are written to a single crontab file owned by the <code>dokku</code> user. The <code>dokku</code> user's crontab should be considered reserved for this purpose.</li> </ul>"},{"location":"processes/scheduled-cron-tasks/#specifying-a-mailto-value","title":"Specifying a MAILTO value","text":"<p>By default, cron tasks complete and do not perform any reporting. Users can specify a value for <code>MAILTO</code> via the global <code>mailto</code> cron property by using the <code>cron:set</code> command.</p> <pre><code>dokku cron:set --global mailto example@example.com\n</code></pre> <p>All output for individual cron runs will be sent to the specified email.</p> <p>Cron emails can be disabled by running the <code>cron:set</code> command for the global <code>mailto</code> property with no value.</p> <pre><code>dokku cron:set --global mailto\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#listing-cron-tasks","title":"Listing Cron tasks","text":"<p>Cron tasks for an app can be listed via the <code>cron:list</code> command. This command takes an <code>app</code> argument.</p> ShellOutput <pre><code>dokku cron:list node-js-app\n</code></pre> <pre><code>ID                                    Schedule   Command\ncGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5  @daily     node index.js\ncGhwPT09dHJ1ZT09PSogKiAqICogKg==      * * * * *  true\n</code></pre> <p>The output can also be displayed in json format:</p> ShellOutput <pre><code>dokku cron:list node-js-app --format json\n</code></pre> <pre><code>[{\"id\":\"cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5\",\"app\":\"node-js-app\",\"command\":\"node index.js\",\"schedule\":\"@daily\"}]\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#executing-a-cron-task-on-the-fly","title":"Executing a cron task on the fly","text":"<p>Cron tasks can be invoked via the <code>cron:run</code> command. This command takes an <code>app</code> argument and a <code>cron id</code> (retrievable from <code>cron:list</code> output).</p> <pre><code>dokku cron:run node-js-app cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5\n</code></pre> <p>By default, the task is run in an attached container - as supported by the scheduler. To run in a background detached container, specify the <code>--detach</code> flag:</p> <pre><code>dokku cron:run node-js-app cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5 --detach\n</code></pre> <p>All one-off cron executions have their containers terminated after invocation.</p>"},{"location":"processes/scheduled-cron-tasks/#displaying-reports","title":"Displaying reports","text":"<p>You can get a report about the cron configuration for apps using the <code>cron:report</code> command:</p> ShellOutput <pre><code>dokku cron:report\n</code></pre> <pre><code>=====&gt; node-js-app cron information\n       Cron task count:               2\n=====&gt; python-sample cron information\n       Cron task count:               0\n=====&gt; ruby-sample cron information\n       Cron task count:               10\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku cron:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app cron information\n       Cron task count:               2\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku cron:report node-js-app --cron-task-count\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#self-managed-cron","title":"Self Managed Cron","text":"<p>Warning</p> <p>Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary.</p> <p>Some installations may require more fine-grained control over cron usage. The following are advanced instructions for configuring cron.</p>"},{"location":"processes/scheduled-cron-tasks/#using-run-for-cron-tasks","title":"Using <code>run</code> for cron tasks","text":"<p>You can always use a one-off container to run an app task:</p> <pre><code>dokku run node-js-app some-command\n</code></pre> <p>For tasks that should not be interrupted, run is the preferred method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.</p>"},{"location":"processes/scheduled-cron-tasks/#using-enter-for-cron-tasks","title":"Using <code>enter</code> for cron tasks","text":"<p>Your Procfile can have the following entry:</p> <pre><code>cron: sleep infinity\n</code></pre> <p>With the <code>cron</code> process scaled to <code>1</code>:</p> <pre><code>dokku ps:scale node-js-app cron=1\n</code></pre> <p>You can now run all your commands in that container:</p> <pre><code>dokku enter node-js-app cron some-command\n</code></pre> <p>Note that you can also run multiple commands at the same time to reduce memory usage, though that may result in polluting the container environment.</p> <p>For tasks that will properly resume, you should use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.</p>"},{"location":"processes/scheduled-cron-tasks/#general-cron-recommendations","title":"General cron recommendations","text":"<p>Regularly scheduled tasks can be a bit of a pain with Dokku. The following are general recommendations to follow to help ensure successful task runs.</p> <ul> <li>Use the <code>dokku</code> user in your cron entry.<ul> <li>If you do not, the <code>dokku</code> binary will attempt to execute with <code>sudo</code>, and your cron run with fail with <code>sudo: no tty present and no askpass program specified</code>.</li> </ul> </li> <li>Add a <code>MAILTO</code> environment variable to ship cron emails to yourself.</li> <li>Add a <code>PATH</code> environment variable or specify the full path to binaries on the host.</li> <li>Add a <code>SHELL</code> environment variable to specify Bash when running commands.</li> <li>Keep your cron tasks in time-sorted order.</li> <li>Keep your server time in UTC so you don't need to translate daylight savings time when reading the cronfile.</li> <li>Run tasks at the lowest traffic times if possible.</li> <li>Use cron to trigger jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.</li> <li>Try to keep tasks quiet so that mails only send on errors.</li> <li>Do not silence standard error or standard out. If you silence the former, you will miss failures. Silencing the latter means you should actually make app changes to handle log levels.</li> <li>Use a service such as Dead Man's Snitch to verify that cron tasks completed successfully.</li> <li>Add lots of comments to your cronfile, including what a task is doing, so that you don't spend time deciphering the file later.</li> <li>Place your cronfiles in a pattern such as <code>/etc/cron.d/APP</code>.</li> <li>Do not use non-ASCII characters in your cronfile names. cron is finicky.</li> <li>Remember to have trailing newlines in your cronfile! cron is finicky.</li> </ul> <p>The following is a sample cronfile that you can use for your apps:</p> <pre><code># server cron jobs\nMAILTO=\"mail@dokku.me\"\nPATH=/usr/local/bin:/usr/bin:/bin\nSHELL=/bin/bash\n\n# m   h   dom mon dow   username command\n# *   *   *   *   *     dokku    command to be executed\n# -   -   -   -   -\n# |   |   |   |   |\n# |   |   |   |   +----- day of week (0 - 6) (Sunday=0)\n# |   |   |   +------- month (1 - 12)\n# |   |   +--------- day of month (1 - 31)\n# |   +----------- hour (0 - 23)\n# +----------- min (0 - 59)\n\n### HIGH TRAFFIC TIME IS B/W 00:00 - 04:00 AND 14:00 - 23:59\n### RUN YOUR TASKS FROM 04:00 - 14:00\n### KEEP SORTED IN TIME ORDER\n\n### PLACE ALL CRON TASKS BELOW\n\n# removes unresponsive users from the subscriber list to decrease bounce rates\n0 0 * * * dokku dokku run node-js-app some-command\n\n# sends out our email alerts to users\n0 1 * * * dokku dokku ps:scale node-js-app cron=1 &amp;&amp; dokku enter node-js-app cron some-other-command &amp;&amp; dokku ps:scale node-js-app cron=0\n\n### PLACE ALL CRON TASKS ABOVE, DO NOT REMOVE THE WHITESPACE AFTER THIS LINE\n</code></pre>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"advanced-usage/backup-recovery/","title":"Backup and Recovery","text":"<p>Info</p> <p>The backup plugin was deprecated in 0.4.x, below are backup recommendations for 0.5.x and later.</p> <p>The best plan for disaster recovery is to always keep multiple (remote) copies of your local repo, static assets and periodic database dumps. Backups should be regularly tested for data integrity and completeness.</p>"},{"location":"advanced-usage/backup-recovery/#tldr","title":"TLDR","text":"<p>Warning</p> <p>This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis.</p>"},{"location":"advanced-usage/backup-recovery/#creating-a-backup","title":"Creating a backup","text":"<p>To create a backup, run the following command at a time when not executing any Dokku commands or app deployments:</p> <pre><code>export BACKUP_TIME=$(date +%Y-%m-%d-%H-%M)\nsudo mkdir -p /var/lib/dokku/services\nsudo chown dokku:dokku /var/lib/dokku/services\nmkdir -p /tmp/dokku-backups/\nsudo tar -czvf \"/tmp/dokku-backups/${BACKUP_TIME}.tar.gz\" /home/dokku /var/lib/dokku/config /var/lib/dokku/data /var/lib/dokku/services /var/lib/dokku/plugins\n</code></pre> <p>This will create a point-in-time backup of your entire Dokku installation in the <code>/tmp/dokku-backups</code> directory. This backup may be moved offsite to another location via rsync, sftp, or some other protocol.</p> <p>It is recommended that backups are regularly cleaned from the originating server and tested as necessary.</p>"},{"location":"advanced-usage/backup-recovery/#restoring-a-backup","title":"Restoring a backup","text":"<p>To extract the backup onto another server, copy the backup to the server and extract it using the following command.</p> <pre><code>sudo tar -xzvf path/to/dokku/backup.tar.gz -C /\n</code></pre> <p>At this point, all datastores should be individually started and checked for data integrity. Once this is complete, individual apps can be rebuilt. Please consult the process management documentation for more information on how to rebuild apps.</p>"},{"location":"advanced-usage/backup-recovery/#caveats","title":"Caveats","text":""},{"location":"advanced-usage/backup-recovery/#app-config","title":"App config","text":"<p>Application config is largely held in a small number of places:</p> <ul> <li><code>/var/lib/dokku/config</code>: Properties set and managed by plugins</li> <li><code>/var/lib/dokku/data</code>: Files generated or extracted by various plugins</li> <li><code>/home/dokku</code>: Certain parts of Dokku core store data in this location</li> </ul> <p>Compressing these directories when no Dokku commands are running is enough to ensure a complete backup of the system.</p>"},{"location":"advanced-usage/backup-recovery/#code-repositories","title":"Code Repositories","text":"<p>Because Dokku is git based, rebuilding a deployed app is as easy as pushing from git. You can push to a new server by updating the <code>dokku</code> remote in you local app's repo.</p> <pre><code>git remote rm dokku\ngit remote add dokku dokku@[dokku.me:dokku.me]\ngit push dokku [master]\n</code></pre>"},{"location":"advanced-usage/backup-recovery/#docker-networks","title":"Docker Networks","text":"<p>Docker networks generated by Dokku should be recreated. Running <code>dokku network:report</code> will output all networks in use by various apps, which can then be used to recreate them via <code>dokku network:create $NETWORK</code>.</p> <p>Networks created by tools other than Dokku may be created as they initially were.</p>"},{"location":"advanced-usage/backup-recovery/#docker-image-and-tar-based-apps","title":"Docker Image and Tar-based Apps","text":"<p>These apps may fail to rebuild via the normal <code>ps:rebuild</code> method. Redeploy these apps by running the original commands used to deploy them</p>"},{"location":"advanced-usage/backup-recovery/#datastores","title":"Datastores","text":"<p>Info</p> <p>Please note that point-in-time backups of the <code>/var/lib/dokku/services</code> directory may contain partially written data due to how various datastores work. Consult the official datastore documentation for the best documentation surrounding proper backup and restore procedures.</p> <p>Some plugins, like the official dokku-postgres plugin, have built-in commands that allow non-volatile data be exported and imported.</p> <p>For dokku-postgres, use:</p> <pre><code>dokku postgres:export [db_name] &gt; [db_name].dump\ndokku postgres:import [db_name] &lt; [db_name].dump\n</code></pre> <p>Additionally, data for official datastores is located in the <code>/var/lib/dokku/services</code> directory. If the directory is restored and the plugin is available, a <code>dokku $SERVICE:start</code> may be enough to restart the service with the underlying data, so long as the datastore version does not change and the underlying data is not corrupt. If this is the case, it may be necessary to re-import all the data onto a fresh version of the datastore service.</p>"},{"location":"advanced-usage/backup-recovery/#plugins","title":"Plugins","text":"<p>The plugin directory is contained at the <code>/var/lib/dokku/plugins</code> directory. Core plugins will automatically be included in new installs, but custom plugins may not. The aforementioned <code>tar</code> creation command will back all plugins up, and the <code>tar</code> extract command will restore the plugins.</p> <p>Note that restoring a plugin will not trigger any <code>install</code> or <code>dependencies</code> triggers. You will need to run these manually. See the plugin management documentation for more information on how to trigger these two hooks.</p>"},{"location":"advanced-usage/backup-recovery/#volumes-and-static-assets","title":"Volumes and Static Assets","text":"<p>Dokku doesn't enforce a 300mb limit on apps, but it's best practice to keep binary assets outside of git. Since containers are considered volatile in Dokku, external stores like s3 or storage mounts should be used for non-volatile items like user uploads. The Dokku storage core plugin can be used to mount local directories / volumes inside the docker container.</p> <p>System administrators are highly encouraged to store persistent data in app-specific subdirectories of the path <code>/var/lib/dokku/data/storage</code>. This will help ensure restores of the aforementioned primary Dokku directories will restore service to all apps.</p> <p>See the persistent storage documentation for more information on how to attach persistent storage to your app.</p>"},{"location":"advanced-usage/backup-recovery/#recovering-app-code","title":"Recovering app code","text":"<p>In case of an emergency when your git repo and backups are completely lost, you can recover the last pushed copy from your remote Dokku server (assuming you still have the ssh key).</p> <pre><code>mkdir [app-name] ; cd !$\ngit init &amp;&amp; git remote add dokku dokku@[dokku.me:app-name]\ngit pull dokku/master &amp;&amp; git checkout dokku/master\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/","title":"Deployment Tasks","text":"<p>New</p> <p>Introduced in 0.5.0</p>"},{"location":"advanced-usage/deployment-tasks/#usage","title":"Usage","text":""},{"location":"advanced-usage/deployment-tasks/#overview","title":"Overview","text":"<p>Sometimes you need to run a command on deployment time, but before an app is completely deployed. Common use cases include:</p> <ul> <li>Checking a database is initialized</li> <li>Running database migrations</li> <li>Any commands required to set up the server (e.g. something like a Django <code>collectstatic</code>)</li> </ul> <p>To support this, Dokku provides support for a special <code>release</code> command within your app's <code>Procfile</code>, as well as a special <code>scripts.dokku</code> key inside of your app's <code>app.json</code> file. Be aware that all commands are run within the context of the built docker image - no commands affect the host unless there are volume mounts attached to your app.</p> <p>Each \"phase\" has different expectations and limitations:</p> <ul> <li><code>app.json</code>: <code>scripts.dokku.predeploy</code><ul> <li>When to use: This should be used if your app does not support arbitrary build commands and you need to make changes to the built image.</li> <li>Are changes committed to the image at this phase: Yes</li> <li>Example use-cases<ul> <li>Bundling assets in a slightly different way</li> <li>Installing a custom package from source or copying a binary into place</li> </ul> </li> </ul> </li> <li><code>app.json</code>: <code>scripts.dokku.postdeploy</code><ul> <li>When to use: This should be used in conjunction with external systems to signal the completion of your deploy.</li> <li>Are changes committed to the image at this phase: No</li> <li>Example use-cases<ul> <li>Notifying slack that your app is deployed</li> <li>Coordinating traffic routing with a central load balancer</li> </ul> </li> </ul> </li> <li><code>app.json</code>: <code>scripts.postdeploy</code><ul> <li>When to use: This should be used when you wish to run a command once, after the app is created and not on subsequent deploys to the app.</li> <li>Are changes committed to the image at this phase: No</li> <li>Example use-cases<ul> <li>Setting up OAuth clients and DNS</li> <li>Loading seed/test data into the app\u2019s test database</li> </ul> </li> </ul> </li> <li><code>Procfile</code>: <code>release</code><ul> <li>When to use: This should be used in conjunction with external systems to signal the completion of your app image build.</li> <li>Are changes committed to the image at this phase: No</li> <li>Example use-cases<ul> <li>Sending CSS, JS, and other assets from your app\u2019s slug to a CDN or S3 bucket</li> <li>Priming or invalidating cache stores</li> <li>Running database migrations</li> </ul> </li> </ul> </li> </ul> <p>Additionally, if using a Dockerfile with an <code>ENTRYPOINT</code>, the deployment task is passed to that entrypoint as is. The exceptions are if the entrypoint is one of the following:</p> <ul> <li><code>[\"/tini\", \"--\"]</code></li> <li><code>[\"/bin/tini\", \"--\"]</code></li> <li><code>[\"/usr/bin/tini\", \"--\"]</code></li> <li><code>[\"/usr/local/bin/tini\", \"--\"]</code></li> </ul> <p>Please keep the above in mind when utilizing deployment tasks.</p> <p>Info</p> <p>To execute commands on the host during a release phase, see the plugin creation documentation docs for more information on building your own custom plugin.</p>"},{"location":"advanced-usage/deployment-tasks/#changing-the-appjson-location","title":"Changing the <code>app.json</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>app.json</code> file to use for a given app. This can be done via the <code>app-json:set</code> command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no <code>app.json</code> file.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>app.json</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>app.json</code> extracted directly from the source code. Both cases will respect the configured <code>appjson-path</code> property value.</p> <pre><code>dokku app-json:set node-js-app appjson-path .dokku/app.json\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku app-json:set node-js-app appjson-path\n</code></pre> <p>The <code>appjson-path</code> property can also be set globally. The global default is <code>app.json</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku app-json:set --global appjson-path global-app.json\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku app-json:set --global appjson-path\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/#displaying-app-json-reports-for-an-app","title":"Displaying app-json reports for an app","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>You can get a report about the app's storage status using the <code>app-json:report</code> command:</p> ShellOutput <pre><code>dokku app-json:report\n</code></pre> <pre><code>=====&gt; node-js-app app-json information\n       App-json computed appjson path: app2.json\n       App-json global appjson path:   app.json\n       App-json appjson path:          app2.json\n=====&gt; python-sample app-json information\n       App-json computed appjson path: app.json\n       App-json global appjson path:   app.json\n       App-json appjson path:\n=====&gt; ruby-sample app-json information\n       App-json computed appjson path: app.json\n       App-json global appjson path:   app.json\n       App-json appjson path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku app-json:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app app-json information\n       App-json computed appjson path: app2.json\n       App-json global appjson path:   app.json\n       App-json appjson path:          app2.json\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku app-json:report node-js-app --app-json-appjson-path\n</code></pre> <pre><code>app2.json\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/#deployment-tasks_1","title":"Deployment tasks","text":""},{"location":"advanced-usage/deployment-tasks/#appjson-deployment-tasks","title":"<code>app.json</code> deployment tasks","text":"<p>Dokku provides limited support for the <code>app.json</code> manifest from Heroku (documentation available here). The keys available for use with Deployment Tasks are:</p> <ul> <li><code>scripts.dokku.predeploy</code>: This is run after an app's docker image is built, but before any containers are scheduled. Changes made to your image are committed at this phase.</li> <li><code>scripts.dokku.postdeploy</code>: This is run after an app's containers are scheduled. Changes made to your image are not committed at this phase.</li> <li><code>scripts.postdeploy</code>: This is run after an app's containers are scheduled. Changes made to your image are not committed at this phase.</li> </ul> <p>Warning</p> <p>Any failed <code>app.json</code> deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers.</p> <p>The following is an example <code>app.json</code> file. Please note that only the <code>scripts.dokku.predeploy</code> and <code>scripts.dokku.postdeploy</code> tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted.</p> <pre><code>{\n  \"scripts\": {\n    \"dokku\": {\n      \"predeploy\": \"touch /app/predeploy.test\",\n      \"postdeploy\": \"curl https://some.external.api.service.com/deployment?state=success\"\n    },\n    \"postdeploy\": \"curl https://some.external.api.service.com/created?state=success\"\n  }\n}\n</code></pre>"},{"location":"advanced-usage/deployment-tasks/#procfile-release-command","title":"Procfile Release command","text":"<p>New</p> <p>Introduced in 0.14.0</p> <p>The <code>Procfile</code> also supports a special <code>release</code> command which acts in a similar way to the Heroku Release Phase. This command is executed after an app's docker image is built, but before any containers are scheduled. This is also run after any command executed by <code>scripts.dokku.predeploy</code>.</p> <p>To use the <code>release</code> command, simply add a <code>release</code> stanza to your Procfile.</p> <pre><code>release: curl https://some.external.api.service.com/deployment?state=built\n</code></pre> <p>Unlike the <code>scripts.dokku.predeploy</code> command, changes made during by the <code>release</code> command are not persisted to disk.</p>"},{"location":"advanced-usage/docker-options/","title":"Docker Container Options","text":"<p>New</p> <p>Introduced in 0.3.17</p> <p>Pass container options to the <code>docker run</code> command  during Dokku's <code>build</code>, <code>deploy</code> and <code>run</code> phases</p> <pre><code>docker-options:add &lt;app&gt; &lt;phase(s)&gt; OPTION    # Add Docker option to app for phase (comma-separated phase list)\ndocker-options:clear &lt;app&gt; [&lt;phase(s)&gt;...]    # Clear a docker options from application\ndocker-options:remove &lt;app&gt; &lt;phase(s)&gt; OPTION # Remove Docker option from app for phase (comma-separated phase list)\ndocker-options:report [&lt;app&gt;] [&lt;flag&gt;]        # Displays a docker options report for one or more apps\n</code></pre> <p>Info</p> <p>When specifying multiple phases, they must be comma-separated without spaces in between each phase, like so:</p> <pre><code>dokku docker-options:add node-js-app deploy,run \"-v /var/log/node-js-app:/app/logs\"\n</code></pre>"},{"location":"advanced-usage/docker-options/#about-dokku-phases","title":"About Dokku phases","text":"<p>Dokku deploys your application in multiple \"phases\" and the <code>docker-options</code> plugin allows you to pass arguments to their underlying docker container:</p> <ul> <li><code>build</code>: the container that executes the appropriate buildpack</li> <li><code>deploy</code>: the container that executes your running/deployed application</li> <li><code>run</code>: the container that executes any arbitrary command via <code>dokku run</code></li> </ul> <p>Manipulation of docker options will not restart running containers. This enables multiple options to be set/unset before final application. As such, changing an app's docker options must be followed by a <code>dokku ps:rebuild</code> in order to take effect.</p> <p>More information on supported Docker options can be found here.</p> <p>Container options configured via the <code>docker-options</code> plugin are not used to modify the process a container runs. Container options are the <code>[OPTIONS]</code> portion of the following, where <code>[CONTAINER_COMMAND]</code> and <code>[ARG]</code> are the process and the arguments passed to it that are launched in the created container: <code>docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]</code>. Please see the documentation for customizing the run command or use a Procfile to modify the command used by a Dockerfile-based container.</p>"},{"location":"advanced-usage/docker-options/#examples","title":"Examples","text":""},{"location":"advanced-usage/docker-options/#add-docker-options","title":"Add Docker options","text":"<p>Add some options for the deployed/running app and when executing <code>dokku run</code>:</p> <pre><code># Mount a host volume in a Docker container: \"-v /host/path:/container/path\"\ndokku docker-options:add node-js-app deploy \"-v /var/log/node-js-app:/app/logs\"\ndokku docker-options:add node-js-app run \"-v /var/log/node-js-app:/app/logs\"\n</code></pre> <p>Note</p> <p>When mounting a host directory in a Dokku app you should first create that directory as user <code>dokku</code> and then mount the directory under <code>/app</code> in the container using <code>docker-options</code> as above. Otherwise the app will lack write permission in the directory.</p>"},{"location":"advanced-usage/docker-options/#remove-a-docker-option","title":"Remove a Docker option","text":"<pre><code>dokku docker-options:remove node-js-app run \"-v /var/log/node-js-app:/app/logs\"\n</code></pre>"},{"location":"advanced-usage/docker-options/#clear-all-docker-options-for-an-app","title":"Clear all Docker options for an app","text":"<p>Docker options can be removed for a specific app using the <code>docker-options:clear</code> command.</p> ShellOutput <pre><code>dokku docker-options:clear node-js-app\n</code></pre> <pre><code>-----&gt; Clearing docker-options for node-js-app on all phases\n</code></pre> <p>One or more valid phases can also be specified. Phases are comma delimited, and specifying an invalid phase will result in an error.</p> ShellOutputShellOutput <pre><code>dokku docker-options:clear node-js-app run\n</code></pre> <pre><code>-----&gt; Clearing docker-options for node-js-app on phase run\n</code></pre> <pre><code>dokku docker-options:clear node-js-app build,run\n</code></pre> <pre><code>-----&gt; Clearing docker-options for node-js-app on phase build\n-----&gt; Clearing docker-options for node-js-app on phase run\n</code></pre>"},{"location":"advanced-usage/docker-options/#displaying-docker-options-reports-for-an-app","title":"Displaying docker-options reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's docker-options status using the <code>docker-options:report</code> command:</p> ShellOutput <pre><code>dokku docker-options:report\n</code></pre> <pre><code>=====&gt; node-js-app docker options information\n       Docker options build:\n       Docker options deploy: -v /var/log/node-js-app:/app/logs\n       Docker options run:  -v /var/log/node-js-app:/app/logs\n=====&gt; python-sample docker options information\n       Docker options build:\n       Docker options deploy:\n       Docker options run:\n=====&gt; ruby-sample docker options information\n       Docker options build:\n       Docker options deploy:\n       Docker options run:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku docker-options:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app docker options information\n       Docker options build:\n       Docker options deploy: -v /var/log/node-js-app:/app/logs\n       Docker options run:  -v /var/log/node-js-app:/app/logs\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku docker-options:report node-js-app --docker-options-build\n</code></pre>"},{"location":"advanced-usage/event-logs/","title":"Dokku Event Logs","text":"<p>New</p> <p>Introduced in 0.3.21</p> <p>Docker provides an events command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones.</p> <pre><code>events [-t]                              # Show the last events (-t follows)\nevents:list                              # List logged events\nevents:on                                # Enable events logger\nevents:off                               # Disable events logger\n</code></pre>"},{"location":"advanced-usage/event-logs/#usage","title":"Usage","text":"<p>Enable the plugin:</p> ShellOutput <pre><code>dokku events:on\n</code></pre> <pre><code>Enabling dokku events logger\n</code></pre> <p>Dokku will then write log entries to <code>/var/log/syslog</code> as well as a Dokku-specific logs sub-directory <code>/var/log/dokku/events.log</code>, which can be easily displayed with the command <code>dokku events</code>:</p> ShellOutput <pre><code>dokku events\n</code></pre> <pre><code>Jul  3 16:09:48 dokku.me dokku[127630]: INVOKED: pre-release-buildpack( pythonapp )\nJul  3 16:10:02 dokku.me dokku[128095]: INVOKED: docker-args-run( rubyapp )\nJul  3 16:10:02 dokku.me dokku[128114]: INVOKED: docker-args-run( nhl )\nJul  3 16:10:03 dokku.me dokku[128195]: INVOKED: pre-deploy( pythonapp )\nJul  3 16:10:23 dokku.me dokku[129253]: INVOKED: docker-args-deploy( pythonapp )\nJul  3 16:10:24 dokku.me dokku[129451]: INVOKED: check-deploy( pythonapp 6274ced0d4be11af4490cd18abaf77cdd593f025133f403d984e80d86a39acec web 5000 10.0.16.80 )\nJul  3 16:10:35 dokku.me dokku[129561]: INVOKED: docker-args-deploy( pythonapp )\nJul  3 16:10:36 dokku.me dokku[129760]: INVOKED: check-deploy( pythonapp ac88a56ee4161ff37e4b92d1498c3eadc91f0aa7c8b81b44fc077e2a51d54cc0 worker )\nJul  3 16:10:46 dokku.me dokku[129851]: INVOKED: post-deploy( pythonapp )\nJul  3 16:10:46 dokku.me dokku[129945]: INVOKED: nginx-pre-reload( pythonapp )\nJul  3 16:15:02 dokku.me dokku[130397]: INVOKED: docker-args-run( goapp )\nJul  3 16:21:02 dokku.me dokku[130796]: INVOKED: docker-args-run( rubyapp )\nJul  3 16:30:02 dokku.me dokku[131384]: INVOKED: docker-args-run( rubyapp )\n</code></pre> <p>You can list all events that are currently being recorded via <code>dokku events:list</code>:</p> ShellOutput <pre><code>dokku events:list\n</code></pre> <pre><code>=====&gt; Events currently logged\ncheck-deploy\ndependencies\ndocker-args-build\ndocker-args-deploy\ndocker-args-run\ngit-post-pull\ngit-pre-pull\nnginx-hostname\nnginx-pre-reload\npost-build-buildpack\npost-build-dockerfile\npost-delete\npost-deploy\npost-domains-update\npre-build-buildpack\npre-build-dockerfile\npre-delete\npre-deploy\npre-release-buildpack\npre-release-dockerfile\nreceive-app\nupdate\n</code></pre>"},{"location":"advanced-usage/persistent-storage/","title":"Persistent Storage","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>The preferred method to mount external containers to a Dokku managed container, is to use the Dokku storage plugin.</p> <pre><code>storage:ensure-directory [--chown option] &lt;directory&gt;  # Creates a persistent storage directory in the recommended storage path\nstorage:list &lt;app&gt; [--format text|json]                # List bind mounts for app's container(s) (host:container)\nstorage:mount &lt;app&gt; &lt;host-dir:container-dir&gt;           # Create a new bind mount\nstorage:report [&lt;app&gt;] [&lt;flag&gt;]                        # Displays a checks report for one or more apps\nstorage:unmount &lt;app&gt; &lt;host-dir:container-dir&gt;         # Remove an existing bind mount\n</code></pre> <p>Info</p> <p>The storage plugin is compatible with storage mounts created with the docker-options. The storage plugin will only list mounts from the deploy/run phase.</p> <p>The storage plugin supports the following mount points:</p> <ul> <li>explicit paths that exist on the host</li> <li>docker volumes</li> </ul>"},{"location":"advanced-usage/persistent-storage/#usage","title":"Usage","text":""},{"location":"advanced-usage/persistent-storage/#listing-persistent-storage","title":"Listing persistent storage","text":"<p>Persistent storage bind mounts are specified on a per-app basis, and can be listed with the <code>storage:list</code> command:</p> ShellOutput <pre><code>dokku storage:list node-js-app\n</code></pre> <pre><code>-----&gt; node-js-app volume bind-mounts:\n       /var/lib/dokku/data/storage/node-js-app:/app/storage\n</code></pre> <p>The output format can also be set to <code>json</code> for programmatic access:</p> ShellOutput <pre><code>dokku storage:list node-js-app --format json\n</code></pre> <pre><code>[\n  {\n    \"host_path\": \"/var/lib/dokku/data/storage/node-js-app\",\n    \"container_path\": \"/app/storage\",\n    \"volume_options\": \"\"\n  }\n]\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#creating-storage-directories","title":"Creating storage directories","text":"<p>New</p> <p>Introduced in 0.25.5</p> <p>A storage directory can be created with the <code>storage:ensure-directory</code> command. This command will create a subdirectory in the recommended <code>/var/lib/dokku/data/storage</code> path - created during Dokku installation - and prepare it for use with an app.</p> ShellOutput <pre><code>dokku storage:ensure-directory node-js-app\n</code></pre> <pre><code>-----&gt; Ensuring /var/lib/dokku/data/storage/node-js-app exists\n       Setting directory ownership to 32767:32767\n       Directory ready for mounting\n</code></pre> <p>By default, permissions are set for usage with Herokuish buildpacks. These permissions can be changed via the <code>--chown</code> option according to the following table:</p> <ul> <li><code>--chown herokuish</code> (default): Use <code>32767:32767</code> as the folder permissions.<ul> <li>This is used for apps deployed with Buildpacks via Herokuish.</li> </ul> </li> <li><code>--chown heroku</code>: Use <code>1000:1000</code> as the folder permissions.<ul> <li>This is used for apps deployed with Cloud Native Buildpacks using the <code>heroku/builder</code> builder.</li> </ul> </li> <li><code>--chown packeto</code>: Use <code>2000:2000</code> as the folder permissions.<ul> <li>This is used for apps deployed with Cloud Native Buildpacks using the <code>cloudfoundry/cnb</code> or <code>packeto</code> builders.</li> </ul> </li> <li><code>--chown root</code>: Use <code>0:0</code> as the folder permissions.<ul> <li>This is used for containers that run their processes as root, as is typical for most Dockerfile or Docker image deploys.</li> </ul> </li> <li><code>--chown false</code>: Skips the <code>chown</code> call.</li> </ul> <p>Users deploying via Dockerfile will want to specify <code>--chown false</code> and manually <code>chown</code> the created directory if the user and/or group id  of the runnning process in the deployed container do not correspond to any of the above options.</p> <p>Warning</p> <p>Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory.</p>"},{"location":"advanced-usage/persistent-storage/#mounting-storage-into-apps","title":"Mounting storage into apps","text":"<p>Dokku supports mounting both explicit host paths as well as docker volumes via the <code>storage:mount</code> command. This takes two arguments, an app name and a <code>host-path:container-path</code> or <code>docker-volume:container-path</code> combination.</p> <pre><code># mount the directory into your container's /app/storage directory, relative to the container root (/)\n# explicit host paths _must_ exist prior to usage.\ndokku storage:mount node-js-app /var/lib/dokku/data/storage/node-js-app:/app/storage\n\n# mount the docker volume into your container's /app/storage directory, relative to the container root (/)\n# docker volumes _must_ exist prior to usage.\ndokku storage:mount node-js-app some-docker-volume:/app/storage\n</code></pre> <p>In the first example, Dokku will then mount the shared contents of <code>/var/lib/dokku/data/storage/node-js-app</code> to <code>/app/storage</code> inside the container.  The mount point is not relative to your app's working directory, and is instead relative to the root (<code>/</code>) of the container. Mounts are only available for containers created via <code>run</code> and by the deploy process, and not during the build process. In addition, the host path is never auto-created by either Dokku or Docker, and should be an explicit path, not one relative to the current working directory.</p> <p>Info</p> <p>If the <code>/storage</code> path within the container had pre-existing content, the container files will be over-written. This may be an issue for users that create assets at build time but then mount a directory at the same place during runtime. Files are not merged.</p> <p>Once persistent storage is mounted, the app requires a restart. See the process scaling documentation for more information.</p> <pre><code>dokku ps:restart app-name\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#unmounting-storage","title":"Unmounting storage","text":"<p>If an app no longer requires a mounted volume or directory, the <code>storage:unmount</code> command can be called. This takes the same arguments as the <code>storage:mount</code> command, an app name and a <code>host-path:container-path</code> or <code>docker-volume:container-path</code> combination.</p> <pre><code># unmount the directory from your container's /app/storage directory, relative to the container root (/)\ndokku storage:unmount node-js-app /var/lib/dokku/data/storage/node-js-app:/app/storage\n\n# unmount the docker volume from your container's /app/storage directory, relative to the container root (/)\ndokku storage:unmount node-js-app some-docker-volume:/app/storage\n</code></pre> <p>Once persistent storage is unmounted, the app requires a restart. See the process scaling documentation for more information.</p> <pre><code>dokku ps:restart app-name\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#displaying-storage-reports-for-an-app","title":"Displaying storage reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's storage status using the <code>storage:report</code> command:</p> ShellOutput <pre><code>dokku storage:report\n</code></pre> <pre><code>=====&gt; node-js-app storage information\n       Storage build mounts:\n       Storage deploy mounts: -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n       Storage run mounts:  -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n=====&gt; python-sample storage information\n       Storage build mounts:\n       Storage deploy mounts:\n       Storage run mounts:\n=====&gt; ruby-sample storage information\n       Storage build mounts:\n       Storage deploy mounts:\n       Storage run mounts:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku storage:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app storage information\n       Storage build mounts:\n       Storage deploy mounts: -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n       Storage run mounts:  -v /var/lib/dokku/data/storage/node-js-app:/app/storage\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku storage:report node-js-app --storage-deploy-mounts\n</code></pre>"},{"location":"advanced-usage/persistent-storage/#use-cases","title":"Use Cases","text":""},{"location":"advanced-usage/persistent-storage/#sharing-storage-across-deploys","title":"Sharing storage across deploys","text":"<p>Dokku is powered by Docker containers, which recommends in their best practices that containers be treated as ephemeral. In order to manage persistent storage for web apps, like user uploads or large binary assets like images, a directory outside the container should be mounted.</p>"},{"location":"advanced-usage/persistent-storage/#shared-storage-between-containers","title":"Shared storage between containers","text":"<p>When scaling your app, you may require a common location to access shared assets between containers, a storage mount can be used in this situation.</p>"},{"location":"advanced-usage/persistent-storage/#shared-storage-across-environments","title":"Shared storage across environments","text":"<p>Your app may be used in a cluster that requires containers or resources not running on the same host access your data. Mounting a shared file service (like S3FS or EFS) inside your container will give you great flexibility.</p>"},{"location":"advanced-usage/persistent-storage/#backing-up","title":"Backing up","text":"<p>Your app may have services that are running in memory and need to be backed up locally (like a key store). Mount a non ephemeral storage mount will allow backups that are not lost when the app is shut down.</p>"},{"location":"advanced-usage/persistent-storage/#build-phase","title":"Build phase","text":"<p>By default, Dokku will only bind storage mounts during the deploy and run phases. Under certain conditions, one might want to bind a storage mount during the build phase. This can be accomplished by using the <code>docker-options</code> plugin directly.</p> <pre><code>dokku docker-options:add node-js-app build \"-v /tmp/python-test:/opt/test\"\n</code></pre> <p>You cannot use mounted volumes during the build phase of a Dockerfile deploy. This is because Docker does not support volumes when executing <code>docker build</code>.</p> <p>Warning</p> <p>This can cause data loss if you bind a mount under <code>/app</code> in buildpack apps as herokuish will attempt to remove the original app path during the build phase.</p>"},{"location":"advanced-usage/persistent-storage/#app-user-and-persistent-storage-file-ownership-buildpack-apps-only","title":"App User and Persistent Storage file ownership (buildpack apps only)","text":"<p>New</p> <p>Introduced in 0.7.1</p> <p>By default, Dokku will execute your buildpack app processes as the <code>herokuishuser</code> user. You may override this by setting the <code>DOKKU_APP_USER</code> config variable.</p> <p>Note</p> <p>this user must exist in your herokuish image.</p> <p>Additionally, the default <code>docker-local</code> scheduler that comes with Dokku will ensure your storage mounts are owned by either <code>herokuishuser</code> or the overridden value you have set in <code>DOKKU_APP_USER</code>. See the docker-local scheduler documentation docs for more information.</p>"},{"location":"advanced-usage/plugin-management/","title":"Plugin Management","text":"<p>New</p> <p>Introduced in 0.4.0</p> <pre><code>plugin:disable &lt;name&gt;                    # Disable an installed plugin (third-party only)\nplugin:enable &lt;name&gt;                     # Enable a previously disabled plugin\nplugin:install [--core|--git-url] [--committish branch|commit|tag] [--name custom-plugin-name]           # Optionally download git-url (and pin to the specified branch/commit/tag) &amp; run install trigger for active plugins (or only core ones)\nplugin:installed &lt;name&gt;                  # Checks if a plugin is installed\nplugin:install-dependencies [--core]     # Run install-dependencies trigger for active plugins (or only core ones)\nplugin:list                              # Print active plugins\nplugin:trigger &lt;args...&gt;.                # Trigger an arbitrary plugin hook\nplugin:uninstall &lt;name&gt;                  # Uninstall a plugin (third-party only)\nplugin:update [name [branch|commit|tag]] # Optionally update named plugin from git (and pin to the specified branch/commit/tag) &amp; run update trigger for active plugins\n</code></pre> <pre><code># for 0.3.x\ncd /var/lib/dokku/plugins\ngit clone &lt;git url&gt;\ndokku plugins-install\n</code></pre> <p>Info</p> <p>These commands require <code>root</code> permissions as the <code>install</code> and <code>install-dependencies</code> plugin triggers may utilize commands such as <code>apt-get</code>. For non-core plugins, please inspect those plugins before running the following command as <code>root</code> user.</p>"},{"location":"advanced-usage/plugin-management/#usage","title":"Usage","text":""},{"location":"advanced-usage/plugin-management/#listing-plugins","title":"Listing Plugins","text":"<p>Installed plugins can be listed via the <code>plugin:list</code> command:</p> ShellOutput <pre><code>dokku plugin:list\n</code></pre> <pre><code>plugn: dev\n  00_dokku-standard    0.32.4 enabled    dokku core standard plugin\n  20_events            0.32.4 enabled    dokku core events logging plugin\n  app-json             0.32.4 enabled    dokku core app-json plugin\n  apps                 0.32.4 enabled    dokku core apps plugin\n  build-env            0.32.4 enabled    dokku core build-env plugin\n  buildpacks           0.32.4 enabled    dokku core buildpacks plugin\n  certs                0.32.4 enabled    dokku core certificate management plugin\n  checks               0.32.4 enabled    dokku core checks plugin\n  common               0.32.4 enabled    dokku core common plugin\n  config               0.32.4 enabled    dokku core config plugin\n  docker-options       0.32.4 enabled    dokku core docker-options plugin\n  domains              0.32.4 enabled    dokku core domains plugin\n  enter                0.32.4 enabled    dokku core enter plugin\n  git                  0.32.4 enabled    dokku core git plugin\n  logs                 0.32.4 enabled    dokku core logs plugin\n  network              0.32.4 enabled    dokku core network plugin\n  nginx-vhosts         0.32.4 enabled    dokku core nginx-vhosts plugin\n  plugin               0.32.4 enabled    dokku core plugin plugin\n  proxy                0.32.4 enabled    dokku core proxy plugin\n  ps                   0.32.4 enabled    dokku core ps plugin\n  repo                 0.32.4 enabled    dokku core repo plugin\n  resource             0.32.4 enabled    dokku core resource plugin\n  scheduler-docker-local 0.32.4 enabled    dokku core scheduler-docker-local plugin\n  shell                0.32.4 enabled    dokku core shell plugin\n  ssh-keys             0.32.4 enabled    dokku core ssh-keys plugin\n  storage              0.32.4 enabled    dokku core storage plugin\n  tags                 0.32.4 enabled    dokku core tags plugin\n  tar                  0.32.4 enabled    dokku core tar plugin\n  trace                0.32.4 enabled    dokku core trace plugin\n</code></pre> <p>Warning</p> <p>All plugin commands other than <code>plugin:list</code> and <code>plugin:help</code> require sudo access and must be run directly from the Dokku server.</p>"},{"location":"advanced-usage/plugin-management/#checking-if-a-plugin-is-installed","title":"Checking if a plugin is installed","text":"<p>You can check if a plugin has been installed via the <code>plugin:installed</code> command:</p> <pre><code>dokku plugin:installed postgres\n</code></pre>"},{"location":"advanced-usage/plugin-management/#installing-a-plugin","title":"Installing a plugin","text":"<p>Note</p> <p>Plugins installed in this method within a docker-based installation of Dokku do not persist across installs. Please see the plugin installation section of the docker-based installation docs for further details.</p> <p>Installing a plugin is easy as well using the <code>plugin:install</code> command. This command will also trigger the <code>install</code> pluginhook on all existing plugins.</p> <p>The most common usage is to install a plugin from a url. This url may be any of the following:</p> <ul> <li><code>git</code>: For git+ssh based plugin repository clones.</li> <li><code>ssh</code>: For git+ssh based plugin repository clones.</li> <li><code>file</code>: For copying plugins from a path on disk.</li> <li><code>https</code>: For http based plugin repository clones.</li> </ul> <p>Additionally, any urls with the extensions <code>.tar.gz</code> or <code>.tgz</code> are treated as Gzipped Tarballs for installation purposes and will be downloaded and extracted into place.</p> ShellOutput <pre><code>dokku plugin:install https://github.com/dokku/dokku-postgres.git\n</code></pre> <pre><code>-----&gt; Cloning plugin repo https://github.com/dokku/dokku-postgres.git to /var/lib/dokku/plugins/available/postgres\nCloning into 'postgres'...\nremote: Counting objects: 646, done.\nremote: Total 646 (delta 0), reused 0 (delta 0), pack-reused 646\nReceiving objects: 100% (646/646), 134.24 KiB | 0 bytes/s, done.\nResolving deltas: 100% (406/406), done.\nChecking connectivity... done.\n-----&gt; Plugin postgres enabled\n</code></pre> <p>For git-based plugin installation, a commit SHA-like object may be specified (tag/branch/commit sha) via the <code>--committish</code> argument and Dokku will attempt to install the specified commit object.</p> <pre><code># where 2.0.0 is a potential git tag\ndokku plugin:install https://github.com/dokku/dokku-postgres.git --committish 2.0.0\n</code></pre> <p>Plugin names are interpolated based on the repository name minus the <code>dokku-</code> prefix. If the plugin being installed has a name other than what matches the repository name - or another name is desired - the <code>--name</code> flag can be used to override this interpolation.</p> <pre><code>dokku plugin:install https://github.com/dokku/smoke-test-plugin.git --name smoke-test-plugin\n</code></pre> <p>The <code>--core</code> flag may also be indicated as the sole argument, though it is only for installation of core plugins, and thus not useful for end-user installations.</p> <pre><code>dokku plugin:install --core\n</code></pre> <p>Finally, all flags may be omitted to trigger the <code>install</code> procedures for both core and third-party plugins:</p> <pre><code>dokku plugin:install\n</code></pre>"},{"location":"advanced-usage/plugin-management/#installing-plugin-dependencies","title":"Installing plugin dependencies","text":"<p>In some cases, plugins will have system-level dependencies. These are not automatically installed via <code>plugin:install</code>, and must be separately via the <code>plugin:install-dependencies</code> command. This will run through all the <code>dependencies</code> trigger for all plugins.</p> <pre><code>dokku plugin:install-dependencies\n</code></pre> <p>This command may also target just core plugins via the <code>--core</code> flag. This is usually only useful for source-based installs of Dokku.</p> <pre><code>dokku plugin:install-dependencies --core\n</code></pre>"},{"location":"advanced-usage/plugin-management/#updating-a-plugin","title":"Updating a plugin","text":"<p>An installed, third-party plugin can be updated can updated via the <code>plugin:update</code> command. This should be done after any upgrades of Dokku as there may be changes in the internal api that require an update of how the plugin interfaces with Dokku.</p> <p>Please note that this command is only valid for plugin installs that were backed by a git-repository.</p> ShellOutput <pre><code>dokku plugin:update postgres\n</code></pre> <pre><code>Plugin (postgres) updated\n</code></pre> <p>An optional commit SHA-like object may be specified.</p> <pre><code>dokku plugin:update postgres 2.0.0\n</code></pre> <p>Any future invocation of <code>plugin:update</code> will respect the previously specified SHA-like object. To follow a particular branch again, specify that branch:</p> <pre><code>dokku plugin:update postgres main\n</code></pre>"},{"location":"advanced-usage/plugin-management/#uninstalling-a-plugin","title":"Uninstalling a plugin","text":"<p>Third party plugins can be uninstalled using the <code>plugin:uninstall</code> command:</p> ShellOutput <pre><code>dokku plugin:uninstall postgres\n</code></pre> <pre><code>-----&gt; Plugin postgres uninstalled\n</code></pre>"},{"location":"advanced-usage/plugin-management/#disabling-a-plugin","title":"Disabling a plugin","text":"<p>Disabling a plugin can also be useful for debugging whether a third-party plugin is causing issues in a Dokku installation. Another common use case is for disabling core functionality for replacement with a third-party plugin.</p> ShellOutput <pre><code>dokku plugin:disable postgres\n</code></pre> <pre><code>-----&gt; Plugin postgres disabled\n</code></pre>"},{"location":"advanced-usage/plugin-management/#enabling-a-plugin","title":"Enabling a plugin","text":"<p>Disabled plugins can be re-enabled via the <code>plugin:enable</code> command.</p> ShellOutput <pre><code>dokku plugin:enable postgres\n</code></pre> <pre><code>-----&gt; Plugin postgres enabled\n</code></pre>"},{"location":"advanced-usage/plugin-management/#triggering-a-plugin-trigger","title":"Triggering a plugin trigger","text":"<p>The <code>plugin:trigger</code> can be used to call any internal plugin trigger. This may have unintended consequences, and thus should only be called for development or debugging purposes.</p> <pre><code>dokku plugin:trigger some-internal-trigger args-go-here\n</code></pre>"},{"location":"advanced-usage/registry-management/","title":"Registry Management","text":"<p>New</p> <p>Introduced in 0.25.0</p> <pre><code>registry:login [--password-stdin] &lt;server&gt; &lt;username&gt; [&lt;password&gt;] # Login to a docker registry\nregistry:report [&lt;app&gt;] [&lt;flag&gt;]                                   # Displays a registry report for one or more apps\nregistry:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)                                 # Set or clear a registry property for an app\n</code></pre> <p>The registry plugin enables interacting with remote registries, which is useful when either deploying images via <code>git:from-image</code> or when interacting with custom schedulers to deploy built image artifacts.</p>"},{"location":"advanced-usage/registry-management/#usage","title":"Usage","text":""},{"location":"advanced-usage/registry-management/#logging-into-a-registry","title":"Logging into a registry","text":"<p>The <code>registry:login</code> command can be used to log into a docker registry. The following are examples for logging into various common registries:</p> <pre><code># hub.docker.com\ndokku registry:login docker.io $USERNAME $PASSWORD\n\n# digitalocean\n# the username and password are both defined as the same api token\ndokku registry:login registry.digitalocean.com $DIGITALOCEAN_API_TOKEN $DIGITALOCEAN_API_TOKEN\n\n# github container registry\n# see the following link for information on retrieving a personal access token\n#   https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images#authenticating-to-github-container-registry\ndokku registry:login ghcr.io $USERNAME $REGISTRY_PAT_TOKEN\n\n# quay\n# a robot user may be used to login\ndokku registry:login quay.io $USERNAME $PASSWORD\n</code></pre> <p>For security reasons, the password may also be specified as stdin by specifying the <code>--password-stdin</code> flag. This is supported regardless of the registry being logged into.</p> <pre><code>echo \"$PASSWORD\" | dokku registry:login --password-stdin docker.io $USERNAME\n</code></pre> <p>For certain Docker registries - such as Amazon ECR or Google's GCR registries - users may instead wish to use a docker credential helper to automatically authenticate against a server; please see the documentation regarding the credential helper in question for further setup instructions.</p>"},{"location":"advanced-usage/registry-management/#setting-a-remote-server","title":"Setting a remote server","text":"<p>To specify a remote server registry for pushes, set the <code>server</code> property via the <code>registry:set</code> command. The default value for this property is empty string. Setting the value to <code>docker.io</code> or <code>hub.docker.com</code> will result in the computed value being empty string (as that is the default, implicit registry), while any non-zero length value will have a <code>/</code> appended to it if there is not one already.</p> <pre><code>dokku registry:set node-js-app server docker.io\n</code></pre> <p>This property can be set for a single app or globally via the <code>--global</code> flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is empty string.</p> <pre><code>dokku registry:set --global server docker.io\n</code></pre> <p>Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.</p> <pre><code># per-app\ndokku registry:set node-js-app server\n\n# globally\ndokku registry:set --global server\n</code></pre> <p>The following are the values that should be used for common remote servers:</p> <ul> <li>Amazon Elastic Container Registry:<ul> <li>value: <code>$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/</code></li> <li>notes: The <code>$AWS_ACCOUNT_ID</code> and <code>$AWS_REGION</code> should match the values for your account and region, respectively. Additionally, an IAM profile that allows <code>push</code> access to the repository specified by <code>image-repo</code> should be attached to your Dokku server.</li> </ul> </li> <li>Azure Container Registry:<ul> <li>value <code>$REGISTRY_NAME.azurecr.io/</code></li> <li>notes: The <code>$AKS_REGISTRY_NAME</code> should match the name of the registry created on your account.</li> </ul> </li> <li>Docker Hub:<ul> <li>value: <code>docker.io/</code></li> <li>notes: Requires owning the namespace used in the <code>image-repo</code> value.</li> </ul> </li> <li>Digitalocean:<ul> <li>value: <code>registry.digitalocean.com/</code></li> <li>notes: Requires setting the correct <code>image-repo</code> value for your registry.</li> </ul> </li> <li>Github Container Registry:<ul> <li>value: <code>ghcr.io/</code></li> <li>notes: Requires that the authenticated user has access to the namespace used in the <code>image-repo</code> value.</li> </ul> </li> <li>Quay.io:<ul> <li>value: <code>quay.io/</code></li> </ul> </li> </ul>"},{"location":"advanced-usage/registry-management/#specifying-an-image-repository-name","title":"Specifying an image repository name","text":"<p>By default, Dokku uses the value <code>dokku/$APP_NAME</code> as the image repository that is pushed and deployed. For certain registries, the <code>dokku</code> namespace may not be available to your user. In these cases, the value can be set by changing the value of the <code>image-repo</code> property via the <code>registry:set</code> command.</p> <pre><code>dokku registry:set node-js-app image-repo my-awesome-prefix/node-js-app\n</code></pre> <p>Setting the property value to an empty string will reset the value to the system default. Resetting the value has to be done per-app.</p> <pre><code># per-app\ndokku registry:set node-js-app image-repo\n</code></pre>"},{"location":"advanced-usage/registry-management/#templating-the-image-repository-name","title":"Templating the image repository name","text":"<p>Instead of setting the image repository name on a per-app basis, it can be set via a template globally with the <code>image-repo-template</code> property:</p> <pre><code>dokku registry:set --global image-repo-template \"my-awesome-prefix/{{ .AppName }}\"\n</code></pre> <p>Dokku uses a Golang template and has access to the <code>AppName</code> variable as shown above.</p>"},{"location":"advanced-usage/registry-management/#pushing-images-on-build","title":"Pushing images on build","text":"<p>To push the image on release, set the <code>push-on-release</code> property to <code>true</code> via the <code>registry:set</code> command. The default value for this property is <code>false</code>. Setting the property to <code>true</code> will result in the image being tagged with an ID that is incremented with every release. This tag will be what is used for running app code.</p> <pre><code>dokku registry:set node-js-app push-on-release true\n</code></pre> <p>This property can be set for a single app or globally via the <code>--global</code> flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is <code>false</code>.</p> <pre><code>dokku registry:set --global push-on-release true\n</code></pre> <p>Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.</p> <pre><code># per-app\ndokku registry:set node-js-app push-on-release\n\n# globally\ndokku registry:set --global push-on-release\n</code></pre>"},{"location":"advanced-usage/repository-management/","title":"Repository Management","text":"<p>New</p> <p>Introduced in 0.6.0</p> <pre><code>repo:gc &lt;app&gt;                            # Runs 'git gc --aggressive' against the application's repo\nrepo:purge-cache &lt;app&gt;                   # Deletes the contents of the build cache stored in the repository\n</code></pre> <p>The repository plugin is meant to allow users to perform management commands against a repository.</p>"},{"location":"advanced-usage/repository-management/#usage","title":"Usage","text":""},{"location":"advanced-usage/repository-management/#git-garbage-collection","title":"Git Garbage Collection","text":"<p>This will run a git gc --aggressive against the applications repo. This is performed on the Dokku host, and not within an application container.</p> ShellOutput <pre><code>dokku repo:gc node-js-app\n</code></pre> <pre><code>Counting objects: 396, done.\nDelta compression using up to 2 threads.\nCompressing objects: 100% (365/365), done.\nWriting objects: 100% (396/396), done.\nTotal 396 (delta 79), reused 315 (delta 0)\n</code></pre>"},{"location":"advanced-usage/repository-management/#clearing-application-cache","title":"Clearing Application cache","text":"<p>Building containers with buildpacks currently results in a persistent <code>cache</code> directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command:</p> <pre><code>dokku repo:purge-cache node-js-app\n</code></pre>"},{"location":"advanced-usage/resource-management/","title":"Resource Management","text":"<p>New</p> <p>Introduced in 0.15.0</p> <pre><code>resource:limit [--process-type &lt;process-type&gt;] [RESOURCE_OPTS...] &lt;app&gt;    # Limit resources for a given app/process-type combination\nresource:limit-clear [--process-type &lt;process-type&gt;] &lt;app&gt;                 # Limit resources for a given app/process-type combination\nresource:report [&lt;app&gt;] [&lt;flag&gt;]                                           # Displays a resource report for one or more apps\nresource:reserve [--process-type &lt;process-type&gt;] [RESOURCE_OPTS...] &lt;app&gt;  # Reserve resources for a given app/process-type combination\nresource:reserve-clear [--process-type &lt;process-type&gt;] &lt;app&gt;               # Reserve resources for a given app/process-type combination\n</code></pre> <p>The resource plugin is meant to allow users to limit or reserve resources for a given app/process-type combination.</p>"},{"location":"advanced-usage/resource-management/#usage","title":"Usage","text":"<p>By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The <code>resource</code> plugin allows management of both resource \"limits\" and resource \"reservations\", where each resource request type has specific meaning to the scheduler in use for a given app.</p> <p>Warning</p> <p>The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect.</p> <p>Valid resource options include:</p> <ul> <li><code>--cpu</code></li> <li><code>--memory</code></li> <li><code>--memory-swap</code></li> <li><code>--network</code></li> <li><code>--network-ingress</code></li> <li><code>--network-egress</code></li> <li><code>--nvidia-gpu</code></li> </ul> <p>See the Supported Resource Management Properties section of the docker local scheduler documentation for more information on how each resource limit maps to Docker.</p> <p>Resource limits and reservations are applied only during the <code>run</code> and <code>deploy</code> phases of an application, and will not impact the <code>build</code> phase of an application.</p>"},{"location":"advanced-usage/resource-management/#resource-limits","title":"Resource Limits","text":"<p>When specified and supported, a resource limit will ensure that your app does not go over the specified value. If this occurs, the underlying scheduler may either cap resource utilization, or it may decide to terminate and reschedule your process.</p> <p>Resource limits may be set via the <code>resource:limit</code> command:</p> ShellOutput <pre><code>dokku resource:limit --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app\n       memory: 100\n</code></pre> <p>Multiple resources can be limited in a single call:</p> ShellOutput <pre><code>dokku resource:limit --cpu 100 --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app\n       cpu: 100\n       memory: 100\n</code></pre> <p>Resources can also be limited on a per-process type basis. If specified, this will override any generic limits set for the app.</p> ShellOutput <pre><code>dokku resource:limit --cpu 100 --memory 100 --process-type worker node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app (worker)\n       cpu: 100\n       memory: 100\n</code></pre> <p>A resource value can be individually cleared by setting the value to the special value <code>clear</code>.</p> ShellOutput <pre><code>dokku resource:limit --cpu clear node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource limits for node-js-app\n       cpu: cleared\n</code></pre>"},{"location":"advanced-usage/resource-management/#displaying-resource-limits","title":"Displaying Resource Limits","text":"<p>Running the <code>resource:limit</code> command without any flags will display the currently configured default app limits.</p> ShellOutput <pre><code>dokku resource:limit node-js-app\n</code></pre> <pre><code>=====&gt; resource limits node-js-app information [defaults]\n       cpu:\n       memory:\n       memory-swap: 100\n       network: 100\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre> <p>This may also be combined with the <code>--process-type</code> flag to see app limits on a process-type level. Note that the displayed values are not merged with the defaults.</p> ShellOutput <pre><code>dokku resource:limit --process-type web node-js-app\n</code></pre> <pre><code>=====&gt; resource limits node-js-app information (web)\n       cpu: 100\n       memory: 100\n       memory-swap:\n       network:\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre>"},{"location":"advanced-usage/resource-management/#clearing-resource-limits","title":"Clearing Resource Limits","text":"<p>In cases where the values are incorrect - or there is no desire to limit resources - resource limits may be cleared using the <code>resource:limit-clear</code> command.</p> ShellOutput <pre><code>dokku resource:limit-clear node-js-app\n</code></pre> <pre><code>-----&gt; Clearing resource limit for node-js-app\n</code></pre> <p>Defaults can also be cleared by leaving the app unspecified.</p> ShellOutput <pre><code>dokku resource:limit-clear\n</code></pre> <pre><code>-----&gt; Clearing default resource limits\n</code></pre>"},{"location":"advanced-usage/resource-management/#resource-reservations","title":"Resource Reservations","text":"<p>When specified and supported, a resource reservation will ensure that your server has at least the specified resources before placing a given app's process. If there a resource exhaustion, future rebuilds and deploys may fail.</p> <p>Resource reservations may be set via the <code>resource:reserve</code> command:</p> ShellOutput <pre><code>dokku resource:reserve --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app\n       memory: 100\n</code></pre> <p>Multiple resources can be limited in a single call:</p> ShellOutput <pre><code>dokku resource:reserve --cpu 100 --memory 100 node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app\n       cpu: 100\n       memory: 100\n</code></pre> <p>Resources can also be limited on a per-process type basis. If specified, this will override any generic limits set for the app.</p> ShellOutput <pre><code>dokku resource:reserve --cpu 100 --memory 100 --process-type worker node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app (worker)\n       cpu: 100\n       memory: 100\n</code></pre> <p>A resource value can be individually cleared by setting the value to the special value <code>clear</code>.</p> ShellOutput <pre><code>dokku resource:reserve --cpu clear node-js-app\n</code></pre> <pre><code>=====&gt; Setting resource reservation for node-js-app\n       cpu: cleared\n</code></pre>"},{"location":"advanced-usage/resource-management/#displaying-resource-reservations","title":"Displaying Resource Reservations","text":"<p>Running the <code>resource:reserve</code> command without any flags will display the currently configured default app reservations.</p> ShellOutput <pre><code>dokku resource:reserve node-js-app\n</code></pre> <pre><code>=====&gt; resource reservation node-js-app information [defaults]\n       cpu: 100\n       memory: 100\n       memory-swap:\n       network:\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre> <p>This may also be combined with the <code>--process-type</code> flag to see app reservations on a process-type level. Note that the displayed values are not merged with the defaults.</p> ShellOutput <pre><code>dokku resource:reserve --process-type web node-js-app\n</code></pre> <pre><code>=====&gt; resource reservation node-js-app information (web)\n       cpu: 100\n       memory: 100\n       memory-swap:\n       network:\n       network-ingress:\n       network-egress:\n       nvidia-gpu:\n</code></pre>"},{"location":"advanced-usage/resource-management/#clearing-resource-reservations","title":"Clearing Resource Reservations","text":"<p>In cases where the values are incorrect - or there is no desire to reserve resources - resource reservations may be cleared using the <code>resource:reserve-clear</code> command.</p> ShellOutput <pre><code>dokku resource:reserve-clear node-js-app\n</code></pre> <pre><code>-----&gt; Clearing resource reservation for node-js-app\n</code></pre> <p>Defaults can also be cleared by leaving the app unspecified.</p> ShellOutput <pre><code>dokku resource:reserve-clear\n</code></pre> <pre><code>-----&gt; Clearing default resource reservation\n</code></pre>"},{"location":"advanced-usage/resource-management/#displaying-resource-reports-for-an-app","title":"Displaying resource reports for an app","text":"<p>You can get a report about the app's resource status using the <code>resource:report</code> command:</p> ShellOutput <pre><code>dokku resource:report\n</code></pre> <pre><code>=====&gt; node-js-app resource information\n       web limit cpu:\n       web limit memory: 1024\n       web limit memory swap: 0\n       web limit network: 10\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory: 512\n       web reservation memory swap:\n       web reservation network: 8\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n=====&gt; python-sample resource information\n       web limit cpu:\n       web limit memory:\n       web limit memory swap:\n       web limit network:\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory:\n       web reservation memory swap:\n       web reservation network:\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n=====&gt; ruby-sample resource information\n       web limit cpu:\n       web limit memory:\n       web limit memory swap:\n       web limit network:\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory:\n       web reservation memory swap:\n       web reservation network:\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku resource:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app resource information\n       web limit cpu:\n       web limit memory: 1024\n       web limit memory swap: 0\n       web limit network: 10\n       web limit network ingress:\n       web limit network egress:\n       web limit nvidia gpu:\n       web reservation cpu:\n       web reservation memory: 512\n       web reservation memory swap:\n       web reservation network: 8\n       web reservation network ingress:\n       web reservation network egress:\n       web reservation nvidia gpu:\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code># Note the periods in the flag name\ndokku resource:report node-js-app --resource-web.limit.memory\n</code></pre> <pre><code>1024\n</code></pre>"},{"location":"appendices/0.10.0-migration-guide/","title":"0.10.0 Migration Guide","text":""},{"location":"appendices/0.10.0-migration-guide/#pci-compliance","title":"PCI Compliance","text":"<p>By default, Dokku will ship a PCI Compliant nginx configuration. For developers whose users are on older browsers or mobile devices, you may need to ship a custom <code>nginx.conf.sigil</code> to enable ciphers for older browsers.</p> <p>See the nginx customization docs for more details.</p>"},{"location":"appendices/0.10.0-migration-guide/#nginx-error-pages","title":"Nginx Error Pages","text":"<p>We now ship with nicer error pages by default. You are free to customize your Dokku installation via a custom <code>nginx.conf.sigil</code> to change what error pages are displayed in different circumstances.</p> <p>See the nginx customization docs for more details.</p>"},{"location":"appendices/0.20.0-migration-guide/","title":"0.20.0 Migration Guide","text":""},{"location":"appendices/0.20.0-migration-guide/#removals","title":"Removals","text":""},{"location":"appendices/0.20.0-migration-guide/#command-removals","title":"Command removals","text":"<p>The following commands were previously deprecated and were removed in this release.</p> <ul> <li><code>apps</code>: Use <code>apps:list</code> instead.</li> <li><code>certs</code>: Use <code>certs:report</code> instead.</li> <li><code>certs:info</code>: Use <code>certs:report</code> instead.</li> <li><code>checks</code>: Use <code>checks:report</code> instead.</li> <li><code>docker-options</code>: Use <code>docker-options:report</code> instead.</li> <li><code>domains</code>: Use <code>domains:report</code> instead.</li> <li><code>plugin</code>: Use <code>plugin:list</code> instead.</li> <li><code>proxy</code>: Use <code>proxy:report</code> instead.</li> <li><code>trace</code>: Use <code>trace:on</code> or <code>trace:off</code> instead.</li> <li><code>ps</code>: Use <code>enter</code> with a container ID instead to run <code>ps auxww</code> within a container.</li> </ul> <p>The refactor of the proxy plugin removes the following functions from being sourced in plugins:</p> <ul> <li><code>proxy#get_app_proxy_port_map()</code></li> <li><code>proxy#list_app_proxy_ports()</code></li> <li><code>proxy#filter_app_proxy_ports()</code></li> <li><code>proxy#add_proxy_ports()</code></li> <li><code>proxy#remove_proxy_ports()</code></li> <li><code>proxy#set_proxy_ports()</code></li> </ul> <p>The informal policy is to allow removal of functions within a <code>functions</code> file if they are not used in OSS plugins. Should you be affected by any such removals, please file an issue to expose the functionality via a plugin trigger.</p>"},{"location":"appendices/0.20.0-migration-guide/#function-renames","title":"Function renames","text":"<ul> <li><code>tar#tar_in_cmd</code> was renamed to <code>tar#cmd-tar-in</code>. Users should avoid using <code>cmd-*</code> commands directly, and instead file an issue to have them exposed via a plugin trigger.</li> <li><code>tar#tar_from_cmd</code> was renamed to <code>tar#cmd-tar-from</code>. Users should avoid using <code>cmd-*</code> commands directly, and instead file an issue to have them exposed via a plugin trigger.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#remove-support-for-unsupported-operating-systems","title":"Remove support for Unsupported Operating Systems","text":"<p>Dokku will no longer distribute packages for Ubuntu versions that have reached either End of Life or End of Standard Support (for LTS releases). This currently includes the following releases:</p> <ul> <li>Ubuntu 14.04 (trusty)</li> <li>Ubuntu 14.10 (utopic)</li> <li>Ubuntu 15.04 (vivid)</li> <li>Ubuntu 15.10 (wily)</li> <li>Ubuntu 16.10 (yakkety)</li> <li>Ubuntu 17.04 (zesty)</li> <li>Ubuntu 17.10 (artful)</li> </ul> <p>Dokku will no longer distribute packages for Debian versions that are not <code>stable</code> or <code>oldstable</code>. This currently includes the following releases:</p> <ul> <li>Debian 7 (wheezy)</li> <li>Debian 8 (jessie)</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#removed-app-report-flags","title":"Removed App report flags","text":"<p>The <code>--git-sha</code> flag was moved from the <code>apps:report</code> command to the <code>git:report</code> command.</p>"},{"location":"appendices/0.20.0-migration-guide/#app-report-output","title":"App report output","text":"<p>When an app is not deployed, the <code>apps:report</code> command no longer shows the message <code>not deployed</code>. Please use the <code>--deployed</code> flag on <code>ps:report</code> instead to see if the app has been deployed.</p>"},{"location":"appendices/0.20.0-migration-guide/#changes","title":"Changes","text":""},{"location":"appendices/0.20.0-migration-guide/#app-report-flags","title":"App report flags","text":"<p>The following changes on the <code>apps:report</code> command were made in this release:</p> <ul> <li>The <code>--deploy-source</code> flag was renamed to <code>--app-deploy-source</code>.</li> <li>The <code>--locked</code> flag was renamed to <code>--app-locked</code>.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#network-report-flags","title":"Network report flags","text":"<p>The following changes on the <code>network:report</code> command were made in this release:</p> <ul> <li>The <code>--network-listeners</code> flag was renamed to <code>--network-web-listeners</code>.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#plugin-triggers","title":"Plugin Triggers","text":"<ul> <li>The <code>network-get-port</code> trigger was incorrectly documented to have the <code>isHerokuishContainer</code> argument as the third argument. The code has been fixed to respect the documentation.</li> <li>The <code>network-get-listeners</code> trigger now takes an additional <code>processType</code> argument. If not specified, it defaults to <code>web</code>. This default will be removed in an upcoming release.</li> </ul>"},{"location":"appendices/0.20.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li><code>nginx:show-conf</code> has been deprecated in favor of <code>nginx:show-config</code>.</li> <li><code>proxy#is_app_proxy_enabled()</code> is deprecated in favor of <code>plugn trigger proxy-is-enabled</code>.</li> <li><code>proxy#get_app_proxy_type()</code> is deprecated in favor of <code>plugn trigger proxy-type</code>.</li> <li><code>apps#apps_create()</code> is deprecated in favor of <code>plugn trigger app-create</code>.</li> <li><code>apps#apps_destroy()</code> is deprecated in favor of <code>plugn trigger app-destroy</code>.</li> <li><code>apps#apps_exists()</code> is deprecated in favor of <code>plugn trigger app-exists</code>.</li> <li><code>apps#apps_maybe_create()</code> is deprecated in favor of <code>plugn trigger app-maybe-create</code>.</li> <li><code>plugin trigger network-get-listeners</code> usage without a second <code>processType</code> argument is deprecated.</li> <li><code>.NGINX_PORT</code> variable usage within <code>nginx.conf.sigil</code> templates is deprecated in favor of <code>.PROXY_PORT</code>.</li> <li><code>.NGINX_SSL_PORT</code> variable usage within <code>nginx.conf.sigil</code> templates is deprecated in favor of <code>.PROXY_SSL_PORT</code>.</li> <li><code>.DOKKU_APP_LISTENERS</code> variable usage within <code>nginx.conf.sigil</code> templates is deprecated in favor of <code>.DOKKU_APP_WEB_LISTENERS</code>.</li> </ul>"},{"location":"appendices/0.21.0-migration-guide/","title":"0.21.0 Migration Guide","text":""},{"location":"appendices/0.21.0-migration-guide/#changes","title":"Changes","text":"<p>The <code>tls</code> name is no longer a reserved app name, and can be used by applications. This was previously a reserved app name due to it's use as a place for global SSL certificate files; Dokku has not supported global SSL certificates for many releases, and thus there is no need to reserve the name.</p>"},{"location":"appendices/0.21.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li><code>git#git_deploy_branch()</code> is deprecated in favor of <code>plugn trigger git-deploy-branch</code>.</li> <li>The <code>config</code> command is deprecated in favor of <code>config:show</code>.<ul> <li>Usage of this command in conjunction with either the <code>--export</code> or <code>--shell</code> flag is deprecated in favor of <code>config:export --format</code> with the correct format value (<code>exports</code> or <code>shell</code>, respectively).</li> </ul> </li> <li>The <code>nginx:build-config</code> command is deprecated in favor of <code>proxy:build-config</code>.</li> </ul>"},{"location":"appendices/0.21.0-migration-guide/#removals","title":"Removals","text":"<p>The <code>apps:destroy</code> command no longer takes a second argument <code>force</code>. Instead, this can be passed as the <code>--force</code> flag, either globally or as a flag to the command itself.</p> <p>The <code>proxy:enable</code> and <code>proxy:disable</code> no longer restart apps when setting the <code>DOKKU_DISABLE_PROXY</code> environment variable. A future release will disable usage of <code>DOKKU_DISABLE_PROXY</code> altogether.</p>"},{"location":"appendices/0.22.0-migration-guide/","title":"0.22.0 Migration Guide","text":""},{"location":"appendices/0.22.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>Calling <code>logs:failed</code> without either a <code>&lt;name&gt;</code> or the <code>--all</code> flag is deprecated.</li> </ul>"},{"location":"appendices/0.22.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>Underscores are no longer valid characters in app names. Please rename applications before upgrading.</li> <li>Process type names specified in Procfile may no longer use characters not valid in DNS Label Names (RFC 1123).</li> <li>The minimum Docker version is now 17.05.0.</li> <li>The <code>common.GetDeployingAppImageName()</code> function now returns an <code>error</code> as the second return argument instead of calling <code>common.LogFail()</code> internally.</li> <li>Setting <code>DOKKU_DISABLE_ANSI_PREFIX_REMOVAL</code> is deprecated; Dokku 0.23.0 will avoid removing the <code>remote:</code> ansi prefix entirely. No warning will be added in this release.</li> </ul>"},{"location":"appendices/0.22.0-migration-guide/#removals","title":"Removals","text":"<p>The <code>ps</code> command has had a few removals as a result of a rewrite to Golang:</p> <ul> <li>The <code>ps:set-restart-policy</code> command has been removed in favor the <code>ps:set</code> command.</li> <li>The <code>ps:restart-policy</code> command has been removed in favor of the <code>ps:report</code> command.</li> <li>The <code>ps:rebuildall</code> command has been removed in favor of calling the <code>ps:rebuild</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>ps:restartall</code> command has been removed in favor of calling the <code>ps:restart</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>ps:stopall</code> command has been removed in favor of calling the <code>ps:stop</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>ps:startall</code> command has been removed in favor of calling the <code>ps:start</code> with the <code>--all</code> flag instead of an app name.</li> <li>The <code>DOKKU_PROCFILE</code> file is no longer located in the git directory for a given app on the server. It's location is currently not exposed.</li> <li>The <code>procfile-get-command</code> plugin trigger no longer takes a <code>procfile path</code> as the final argument.</li> <li>All <code>ps</code> functions have been removed. Please us a trigger as appropriate or file a PR to have a new trigger/wrapper function added.</li> </ul>"},{"location":"appendices/0.23.0-migration-guide/","title":"0.23.0 Migration Guide","text":""},{"location":"appendices/0.23.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The <code>plugin:list</code> command no longer outputs the version for the <code>plugn</code> binary.</li> <li>Users building docker images that run Dokku will need to use a new sudoer wrapper for the <code>docker-image-labeler</code> binary to work correctly. A reference version has been placed in the <code>docker</code> skeleton directory. This should only impact platform developers, and users of our Docker image will already have the file available.</li> <li>The <code>dokku</code> user's cron is now in use by Dokku itself. Customizations will be overwritten. Users are encouraged to use a cron entry in <code>/etc/cron.d/dokku</code> to avoid this issue.</li> <li>As of 0.23.0, Dokku will now inject the <code>max-size</code> log driver option for applications. This is restricted to app-configured log driver values empty, <code>local</code> or <code>json-file</code> in 0.23.1 to increase setup compatibility. Users who configure alternative log drivers at the system level will need to either set the global <code>max-size</code> property to <code>unlimited</code> or switch to the built-in <code>vector</code> logging support.</li> </ul>"},{"location":"appendices/0.24.0-migration-guide/","title":"0.24.0 Migration Guide","text":""},{"location":"appendices/0.24.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The commands <code>proxy:enable</code>, <code>proxy:disable</code> and <code>proxy:build-config</code> now support the <code>--all</code> flag in addition to general parallelism.</li> <li>The <code>builder-cnb</code> plugin has been renamed <code>builder-pack</code>, and all related plugin triggers have had the suffix <code>-cnb</code> changed to <code>-pack</code>.</li> </ul>"},{"location":"appendices/0.24.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>The 1.0.0 release of Dokku will no longer select buildpack builders over dockerfile builders if both builders match. Instead, Dokku will choose the first builder that responds to the <code>builder-detect</code> trigger. Users that wish to use a specific builder may set a builder using the <code>builder:set</code> command, which will force Dokku to use the specified builder regardless of what might be auto-detected.</li> <li>The <code>tags</code> plugin is deprecated in favor of the <code>git:from-image</code> command. It will be removed in the next minor release, and is considered unmaintained. Users are highly encouraged to switch their workflows to <code>git:from-image</code>.</li> <li>The <code>tar</code> plugin is deprecated in favor of the <code>git:from-archive</code> command. It will be removed in the next minor release, and is considered unmaintained. Users are highly encouraged to switch their workflows to <code>git:from-archive</code>.</li> </ul>"},{"location":"appendices/0.25.0-migration-guide/","title":"0.25.0 Migration Guide","text":""},{"location":"appendices/0.25.0-migration-guide/#registry-plugin","title":"Registry Plugin","text":"<p>The dokku-registry plugin is now built-in. This comes with a few changes:</p> <ul> <li>Builder plugins should call <code>post-release-builder</code> at the end of the build.</li> <li>The <code>push</code> and <code>pull</code> command are not implemented. Users wishing to deploy a remote image should use <code>git:from-image</code>. Image pushing is not available at this time.</li> <li>At this time, remote docker repositories are not automatically created for AWS, and users must create those repositories for their applications as necessary. This may be implemented in the future.</li> <li>Docker images are only pushed when configured to do so. See the registry management documentation for more details.</li> </ul> <p>Before upgrading, uninstall the registry plugin via <code>dokku plugin:uninstall registry</code>. Not doing so will cause issues with Dokku.</p>"},{"location":"appendices/0.25.0-migration-guide/#other","title":"Other","text":""},{"location":"appendices/0.25.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The network plugin can now set an <code>initial-network</code> for all containers on creation. This is a replacement for specifying the <code>--network</code> flag via the <code>docker-options</code> plugin. Please see the network documentation for more information.</li> <li>The <code>dokku run</code> command now always removes the ephemeral container on exit. Users that need a persistent container should instead specify a <code>console</code> process type in their <code>Procfile</code> specifying an available shell (usually either <code>bash</code> or <code>sh</code>) and scale that container appropriately.</li> <li>The <code>pre-deploy</code> plugin trigger is now called internally by Dokku. Scheduler plugins should avoid calling this trigger, as any image changes introduced by subsequent trigger calls will be ignored.</li> <li>The default image used for Herokuish Buildpack builds is now <code>gliderlabs/herokuish:latest-20</code>, and is based on both the <code>heroku-20</code> stack as well as Ubuntu 20.04. Users that wish to stick with the old, <code>heroku-18</code>/Ubuntu 18.04 builder may specify <code>gliderlabs/herokuish:latest-18</code> as their builder image. Please see the herokuish buildpack deployment documentation for more information on how to specify a custom buildpack stack builder.<ul> <li>This change does not impact any users of Cloud Native Buildpacks.</li> </ul> </li> <li>We fixed an issue that required extracting Procfiles at the beginning of a deploy. Due to this change, a <code>Dockerfile</code> app contains a <code>Procfile</code> that does not specify a <code>web</code> process will fail to start. Usage of a <code>Procfile</code> with only a <code>release</code> command should be replaced with a <code>scripts.dokku.postdeploy</code> deployment task in the <code>app.json</code> file. The alternative is to define the <code>web</code> process in the <code>Procfile</code>. See the deployment task documentation for more information.</li> </ul>"},{"location":"appendices/0.25.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>In previous versions of Dokku, the only way to specify a custom <code>Dockerfile</code> was to use the <code>docker-options</code> plugin to set the <code>--file</code> flag for a docker build. As of 0.25.0, the <code>builder-dockerfile:set</code> command should be used instead, as outlined in the docs here. Usage of the old method should be migrated to the new method.</li> <li>The <code>--rm</code> and <code>--rm-container</code> flags may be specified but no longer have any effect on <code>dokku run</code>.</li> <li>The <code>--detach</code> flag is deprecated in favor of the <code>run:detached</code> command.</li> <li>The <code>DOKKU_SCALE</code> file is deprecated. Please see the process management documentation for more information on it's replacement with the <code>formation</code> key of the <code>app.json</code> file.</li> <li>The hooks <code>post-release-buildpack</code>, <code>post-release-dockerfile</code>, and <code>post-release-pack</code> are deprecated in favor of <code>post-release-builder</code>. See the plugin triggers documentation for more details.</li> </ul>"},{"location":"appendices/0.25.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>As of April 2021, Ubuntu 16.04 is no longer an LTS release, and support has been removed. Packages may still install on older versions of Ubuntu, but are no longer tested, and therefore no support will be provided.</li> <li>The web installer has been removed. Users are now required to setup Dokku via cli commands. This change was made to combat potential security issues where users ignored the web installer, allowing unauthorized users to add their keys to the host.</li> <li>The <code>scheduler-docker-cleanup</code> plugin trigger has been removed from the scheduler interface, and is no longer invoked.</li> </ul>"},{"location":"appendices/0.26.0-migration-guide/","title":"0.26.0 Migration Guide","text":""},{"location":"appendices/0.26.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>The <code>tags</code> plugin - deprecated in 0.24.0 - was removed. Users are highly encouraged to switch their workflows to <code>git:from-image</code>.</li> <li>The <code>tar</code> plugin - deprecated in 0.24.0 - was removed. Users are highly encouraged to switch their workflows to <code>git:from-archive</code>.</li> </ul>"},{"location":"appendices/0.26.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The <code>scheduler</code> plugin now controls the scheduler in use for deploys. Apps will have their <code>DOKKU_SCHEDULER</code> environment variables migrated to the scheduler plugin, after which that value will be removed from said app. Please see the scheduler documentation for more information.</li> <li>The <code>deploy-source</code> metadata from <code>apps:report</code> is now no longer computed on the fly, but hydrated at deploy time via the <code>deploy-source-set</code> trigger. This value may be empty until your next deploy.<ul> <li>Additionally, the <code>deploy-source</code> trigger has now been removed.</li> </ul> </li> </ul>"},{"location":"appendices/0.27.0-migration-guide/","title":"0.27.0 Migration Guide","text":""},{"location":"appendices/0.27.0-migration-guide/#changes","title":"Changes","text":"<ul> <li> <p>Renaming an application will now only rename domains that are associated with global domains. As an example:</p> <pre><code>dokku domains:set-global dokku.me\ndokku apps:create node-js-app\ndokku domains:set node-js-app node-js-app.dokku.me node-js-app.dokku.com\ndokku apps:rename node-js-app other-name\ndokku domains:report node-js-app --domains-app-vhosts\n# output: other-name.dokku.me node-js-app.dokku.com\n</code></pre> </li> </ul>"},{"location":"appendices/0.28.0-migration-guide/","title":"0.28.0 Migration Guide","text":""},{"location":"appendices/0.28.0-migration-guide/#removals","title":"Removals","text":"<p>Support for the following operating systems has been removed:</p> <ul> <li>CentOS 7</li> <li>Debian 9 (Stretch)</li> <li>Fedora</li> <li>OpenSuse</li> </ul> <p>Dokku will no longer provide packages for RPM based systems. Debian 9 users may use new Debian packages, though support is not guaranteed.</p> <p>All users are encouraged to install Dokku via the Docker-based installation method, or switch to a supported operating system.</p>"},{"location":"appendices/0.28.0-migration-guide/#deprecations","title":"Deprecations","text":"<p>Ubuntu 18.04 is now a deprecated installation target. The operating system will be considered EOL by Canonical in April 2023. Users are encouraged to upgrade to Ubuntu 22.04 or consider switching their instllation method to the Docker-based installation method to avoid any disruption in usage.</p>"},{"location":"appendices/0.28.0-migration-guide/#additions","title":"Additions","text":"<p>New in 0.28.0 are the Caddy, Haproxy and Traefik plugins. As community plugins wrapping these proxies exist, users should:</p> <ul> <li>Recommended: Uninstall the community plugin in question and switch all config to the new plugins.</li> <li>Upgrade the community plugin to a version that does not use the <code>proxy:set</code> value of <code>caddy</code>, <code>haproxy</code> or <code>traefik</code>.</li> </ul>"},{"location":"appendices/0.29.0-migration-guide/","title":"0.29.0 Migration Guide","text":""},{"location":"appendices/0.29.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The output of <code>run:detached</code> now uses the container name - eg. <code>node-js-app.run.1</code> - vs the container id.</li> <li>The ID of <code>cron</code> tasks is now base36-encoded instead of base64-encoded.</li> <li>The <code>nginx.conf.sigil</code> is now extracted when source code is extracted for a build and not from the built image. Users can specify alternative paths via the <code>nginx-conf-sigil-path</code> property of the <code>nginx</code> plugin. See the nginx documentation for more information on how to configure the <code>nginx.conf.sigil</code> path for your application.<ul> <li>For deploys via <code>git:from-image</code>, the <code>nginx.conf.sigil</code> file will be extracted from the source image, respecting the value of <code>nginx-conf-sigil-path</code>.</li> </ul> </li> <li>The <code>Procfile</code> is now extracted when source code is extracted for a build and not from the built image. Users can specify alternative paths via the <code>procfile-path</code> property of the <code>ps</code> plugin. See the process management documentation for more information on how to configure the <code>Procfile</code> path for your application.<ul> <li>For deploys via <code>git:from-image</code>, the <code>Procfile</code> file will be extracted from the source image, respecting the value of <code>procfile-path</code>.</li> </ul> </li> <li>The existing <code>pre-restore</code> hook has been renamed to <code>scheduler-pre-restore</code>. There is a new <code>pre-restore</code> hook that is triggered within the <code>ps:restore</code> command prior to restoring any apps.</li> <li>Nginx init commands are now performed via systemctl on Ubuntu systems when <code>/usr/bin/systemctl</code> is available.</li> </ul>"},{"location":"appendices/0.29.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>The <code>DOKKU_WAIT_TO_RETIRE</code> environment variable has been migrated to a <code>checks</code> property named <code>wait-to-retire</code> and will be ignored if set as an environment variable.</li> <li>The <code>domains-setup</code> trigger has been removed. Initial app domains will now be automatically setup during app creation.</li> <li>The <code>URLS</code> file containing generated urls for an app is no longer generated or referenced. Users should retrieve app urls via the new <code>domains-urls</code> plugin trigger.</li> <li>The common function <code>get_app_urls</code> has been removed. Users should retrieve app urls via the new <code>domains-urls</code> plugin trigger.</li> </ul>"},{"location":"appendices/0.30.0-migration-guide/","title":"0.30.0 Migration Guide","text":"<p>Info</p> <p>Important: Due to the removal of <code>DOKKU_SCALE</code> support, users with a version older than 0.25.x are heavily encouraged to upgrade to 0.29.x prior to 0.30.x. Not doing so will result in all app containers stopping on rebuild due to having no scale settings.</p>"},{"location":"appendices/0.30.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>Support for Ubuntu 18.04 has been deprecated. Please upgrade your host OS in advance of the End Of Life in April 2023.</li> </ul>"},{"location":"appendices/0.30.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>The <code>app.json</code> file is now extracted from the source code instead of the built image. For deploys via <code>git:from-image</code>, the file is extracted from the built image.</li> </ul>"},{"location":"appendices/0.30.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>Support for SPDY has been removed. No major browser supports it as of 2021. Custom <code>nginx.conf.sigil</code> templates referencing spdy-related variables will continue to build until the 1.0.0 release.</li> <li>Support for the <code>DOKKU_SCALE</code> file - deprecated in 0.25.0 - has been removed in favor of the <code>formation</code> key in the <code>app.json</code> file. Please see the process management documentation for more information on how to use the <code>formation</code> key of the <code>app.json</code> file.</li> <li>The deprecated <code>--detach</code> global flag for <code>dokku run</code> was removed. Please see the one-off tasks documentation for more information on running detached containers.</li> <li>The following deprecated trigger have been removed in favor of the <code>post-release-builder</code> trigger. See the plugin triggers documentation for more details.<ul> <li><code>post-release-buildpack</code></li> <li><code>post-release-dockerfile</code></li> <li><code>post-release-pack</code></li> </ul> </li> <li>The ability to call <code>logs:failed</code> without specifying an app or <code>--all</code> flag has been removed. This was deprecated in 0.22.0. Please see the logs:failed.</li> <li>The following app shell functions - deprecated since 0.20.0 - have been removed in favor of their plugin trigger equivalents. Sourcing the <code>app/functions</code> file will fail going forward.<ul> <li><code>apps#apps_create()</code> is removed in favor of <code>plugn trigger app-create</code>.</li> <li><code>apps#apps_destroy()</code> is removed in favor of <code>plugn trigger app-destroy</code>.</li> <li><code>apps#apps_exists()</code> is removed in favor of <code>plugn trigger app-exists</code>.</li> <li><code>apps#apps_maybe_create()</code> is removed in favor of <code>plugn trigger app-maybe-create</code>.</li> </ul> </li> <li>The following common shell functions have been removed:<ul> <li><code>common#is_container_running()</code> (deprecated since 0.12.6) is removed in favor of <code>common#is_container_status()</code>.</li> <li><code>common#is_app_running()</code> (deprecated since 0.22.0) is removed in favor of <code>ps#fn-ps-is-app-running()</code>.</li> </ul> </li> <li>The global <code>--rm-container</code> and <code>--rm</code> flags - deprecated since 0.25.0 - have been removed.</li> <li>The following git shell functions have been removed:<ul> <li><code>git#use_git_worktree()</code> (deprecated since 0.23.7) has been removed. There is no alternative as the function has been made internal.</li> <li><code>git#git_deploy_branch()</code>(deprecated since 0.21.0) has been removed in favor of <code>plugn trigger git-deploy-branch</code>.</li> </ul> </li> <li>The following nginx commands - deprecated since 0.20.0 - have been removed:<ul> <li><code>nginx:show-conf</code> has been removed in favor of <code>nginx:show-config</code>.</li> <li><code>nginx:validate</code> has been removed in favor of <code>nginx:validate-config</code>.</li> <li><code>nginx:build-config</code> - deprecated since 0.21.0 - has been removed in favor of <code>proxy:build-config</code>.</li> </ul> </li> <li>The following proxy functions - deprecated since 0.20.0 - have been removed in favor of their plugin trigger equivalents. Sourcing the <code>proxy/functions</code> file will fail going forward.<ul> <li><code>proxy#is_app_proxy_enabled()</code> is removed in favor of <code>plugn trigger proxy-is-enabled</code>.</li> <li><code>proxy#get_app_proxy_type()</code> is removed in favor of <code>plugn trigger proxy-type</code>.</li> </ul> </li> </ul>"},{"location":"appendices/0.31.0-migration-guide/","title":"0.31.0 Migration Guide","text":""},{"location":"appendices/0.31.0-migration-guide/#changes","title":"Changes","text":"<ul> <li>Herokuish build cache is now mounted from a docker volume - eg. <code>cache-node-js-app</code> - instead of the local filesystem. All existing app cache will be cleared upon upgrading past 0.29.0.</li> <li>The <code>vector</code> container integration now mounts config to <code>/etc/vector</code> instead of the path <code>/etc/vector/vector.json</code>, allowing users the ability to provide extra configuration for Vector Sinks. To take advantage of the new functionality, the vector container should be stopped (via <code>dokku logs:vector-stop</code>) and then started (via <code>dokku logs:vector-start</code>).</li> <li>The <code>traefik</code> integration now mounts config to <code>/data</code> instead of the path <code>/acme.json</code>, fixing permissions issues under certain architectures. To take advantage of the new functionality, the traefik container should be stopped (via <code>dokku traefik:stop</code>) and then started (via <code>dokku traefik:start</code>).</li> <li>Users no longer need to clear the <code>source-image</code> git property when transitioning from image-based deploys (<code>git:from-image</code> and <code>git:load-image</code>) to other deployment methods (git push, <code>git:from-archive</code>, <code>git:sync</code>).</li> <li>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>CHECKS</code> file is now extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>CHECKS</code> extracted directly from the source code. The filename in both cases is <code>CHECKS</code> and cannot be modified.</li> <li>Port mappings are now auto-detected during the build process. Users may override detected port mappings via the <code>ports</code> plugin. A default port mapping of <code>http:80:5000</code> will be used if none is otherwise specified.</li> <li>Users building docker images that run Dokku will need to use a new sudoer wrapper for the <code>docker-container-healthchecker</code> binary to work correctly. A reference version has been placed in the <code>docker</code> skeleton directory. This should only impact platform developers, and users of our Docker image will already have the file available.</li> <li>The default image used for Herokuish Buildpack builds is now <code>gliderlabs/herokuish:latest-22</code>, and is based on both the <code>heroku-22</code> stack as well as Ubuntu 22.04. Users that wish to stick with the old, <code>heroku-20</code>/Ubuntu 20.04 builder may specify <code>gliderlabs/herokuish:latest-20</code> as their builder image. Please see the herokuish buildpack deployment documentation for more information on how to specify a custom buildpack stack builder.</li> <li>The default image used for Cloud Native Buildpack builds is now <code>heroku/builder:22</code>, and is based on both the <code>heroku-22</code> stack as well as Ubuntu 22.04. Users that wish to stick with the old, <code>heroku-20</code>/Ubuntu 20.04 builder may specify <code>heroku/buildpacks:20</code> as their builder image. Please see the herokuish buildpack deployment documentation for more information on how to specify a custom buildpack stack builder.</li> </ul>"},{"location":"appendices/0.31.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>The <code>proxy:ports*</code> commands have been replaced with the new <code>ports</code> plugin. Users will be able to use the old <code>proxy:ports*</code> commands for a single minor release, and they will be removed in the next minor release.</li> <li>The <code>common#get_available_port()</code> function has been deprecated and will be removed in the next release. Users should avoid interacting with this function and instead use the <code>ports-get-available</code> plugin trigger for fetching an available port.</li> <li>The <code>proxy-configure-ports</code> plugin trigger has been deprecated and will be removed in the next release. Users should instead trigger the <code>ports-configure</code> plugin trigger.</li> <li>The <code>common#get_dockerfile_exposed_ports()</code> function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was in the <code>builder-dockerfile</code> plugin.</li> <li>The <code>common#get_exposed_ports_from_image()</code> function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was during the build process.</li> <li>The environment variable <code>DOKKU_PROXY_PORT_MAP</code> has been migrated to the properties system. Direct changes to the value will be ignored, and users should interact with port maps via the <code>ports</code> plugin.</li> <li>The <code>CHECKS</code> file is deprecated in favor of defining healthchecks in the <code>app.json</code> file. The docker-container-healthchecker tool can be used to generate healthcheck entries in <code>app.json</code> format from existing <code>CHECKS</code> files. See the zero-downtime deploy documentation for more information on how the new zero downtime check format works.</li> <li>ARM support is now deprecated, and will be removed in the next minor release. ARM releases are not tested in CI and do not get testing locally. Users of ARM installations on platforms such as the Raspberry PI should consider migrating to ARM64. ARM64 will continue to be supported by Dokku, and there are no plans to remove support for ARM64.</li> </ul>"},{"location":"appendices/0.31.0-migration-guide/#un-deprecations","title":"Un-Deprecations","text":"<ul> <li>The bare <code>apps</code> and <code>config</code> cli aliases are no longer deprecated. This better follows Heroku's output and is more useful to users. The subcommands will be treated as the primary, documented versions, while the aliases are there for convenience.</li> </ul>"},{"location":"appendices/0.31.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>The variable <code>RAW_TCP_PORTS</code> is no longer exposed for <code>nginx.conf.sigil</code> templating.</li> <li>The environment variable <code>DOKKU_DOCKERFILE_PORTS</code> is no longer in use. Users wishing to change port mappings should instead use the <code>ports</code> plugin.</li> <li>The <code>common#get_app_raw_tcp_ports()</code> function has been removed in the next release. Users should instead use the <code>ports-get</code> plugin trigger for fetching ports for an app.</li> <li>The plugin trigger <code>network-compute-ports</code> has been removed. It's only use was in the <code>scheduler-docker-local</code> plugin, for exposing ports. It's functionality is now implemented via the <code>ports</code> plugin.</li> <li>The plugin trigger <code>network-get-port</code> has been removed. It's only use was in the <code>scheduler-docker-local</code> plugin, for recording ports. It's functionality is now implemented via the <code>ports</code> plugin.</li> </ul>"},{"location":"appendices/0.32.0-migration-guide/","title":"0.32.0 Migration Guide","text":""},{"location":"appendices/0.32.0-migration-guide/#deprecations","title":"Deprecations","text":"<ul> <li>The following <code>pre-build-*</code> plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the <code>pre-build</code> plugin trigger.<ul> <li>pre-build-buildpack</li> <li>pre-build-dockerfile</li> <li>pre-build-lambda</li> <li>pre-build-pack</li> </ul> </li> <li>The following <code>pre-release-*</code> plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the <code>pre-release-builder</code> plugin trigger.<ul> <li>pre-release-buildpack</li> <li>pre-release-dockerfile</li> <li>pre-release-lambda</li> <li>pre-release-pack</li> </ul> </li> <li>The following <code>post-build-*</code> plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the <code>post-build</code> plugin trigger.<ul> <li>post-build-buildpack</li> <li>post-build-dockerfile</li> <li>post-build-lambda</li> <li>post-build-pack</li> </ul> </li> <li>The <code>CHECKS</code> file was deprecated in the previous release in favor of defining healthchecks in the <code>app.json</code> file. It's support and auto-migration to healthchecks in the <code>app.json</code> file will be removed in the next release. See the zero-downtime deploy documentation for more information on how the new zero downtime check format works.</li> </ul>"},{"location":"appendices/0.32.0-migration-guide/#removals","title":"Removals","text":"<ul> <li>ARM support has been removed. Users of ARM installations on platforms such as the Raspberry PI should consider migrating to ARM64. ARM64 will continue to be supported by Dokku, and there are no plans to remove support for ARM64.</li> <li>The following proxy-port related code has been removed. It is replaced by the <code>ports</code> plugin and it's related plugin triggers.<ul> <li><code>proxy:ports-*</code> commands</li> <li><code>proxy-configure-ports</code> plugin trigger</li> <li><code>common#get_available_port()</code></li> <li><code>common#get_dockerfile_exposed_ports()</code></li> <li><code>common#get_exposed_ports_from_image()</code></li> </ul> </li> </ul>"},{"location":"appendices/0.5.0-migration-guide/","title":"0.5.0 Migration Guide","text":""},{"location":"appendices/0.5.0-migration-guide/#nginx-vhosts-plugin","title":"<code>nginx-vhosts</code> plugin","text":"<ul> <li>The nginx-vhosts template language is now sigil<ul> <li>No need to escape literal <code>$</code> characters (or other \"bash-isms\")</li> <li>Template variables are represented as {{ .VARIABLE_NAME }}</li> <li>A detailed list of template variables can be found here</li> </ul> </li> <li>A custom nginx-vhosts template must be named <code>nginx.conf.sigil</code><ul> <li>The default path for this custom template is the root of your repo (i.e. <code>/app</code> in the container or <code>WORKDIR</code> if defined in a dockerfile app)</li> <li>Dokku no longer looks for this file in <code>/home/dokku/node-js-app</code> on the Dokku server</li> <li>Check out an example template here</li> </ul> </li> <li>Support for server-wide SSL certs have been dropped in favor of using the <code>certs</code> plugin<ul> <li><code>dokku certs:add node-js-app &lt; certs.tar</code></li> </ul> </li> <li>All domains for an SSL-enabled app will be redirected to https by default<ul> <li>This can be overridden with a custom template</li> </ul> </li> <li>Replaced \"magic\" <code>NO_VHOST</code> variable with <code>domains:enable/disable</code></li> <li>Simplified zero downtime control<ul> <li><code>checks:enable/disable</code></li> </ul> </li> </ul>"},{"location":"appendices/0.5.0-migration-guide/#dockerfile-apps-with-exposed-ports","title":"Dockerfile apps with exposed ports","text":"<ul> <li>Dockerfiles with <code>EXPOSE</code> clauses will get all tcp ports proxied by default<ul> <li>Note that nginx will proxy the same port numbers to listen publicly</li> <li>UDP ports can be exposed by disabling the nginx proxy with <code>dokku proxy:disable node-js-app</code></li> </ul> </li> </ul>"},{"location":"appendices/0.6.0-migration-guide/","title":"0.6.0 Migration Guide","text":""},{"location":"appendices/0.6.0-migration-guide/#zero-downtime-deployment","title":"Zero-downtime deployment","text":"<ul> <li>You can now actually disable zero-downtime deployments per-app and per-process-type<ul> <li>Some config variables have been moved around<ul> <li><code>DOKKU_CHECKS_ENABLED</code> has been migrated to <code>DOKKU_CHECKS_SKIPPED</code></li> <li><code>DOKKU_CHECKS_DISABLED</code> is now a thing</li> <li>The values for the above can be a comma-separated list of process-types or the literal string <code>_all_</code></li> </ul> </li> <li>See the updated <code>checks</code> docs for more info</li> </ul> </li> </ul>"},{"location":"appendices/0.6.0-migration-guide/#proxy-port-mapping","title":"Proxy port mapping","text":"<ul> <li>You can now configure host -&gt; container proxy port mappings<ul> <li>The UI is handled by the proxy interface plugin by setting the <code>DOKKU_PROXY_PORT_MAP</code> config variable in the format of <code>scheme:host-port:container-port</code>. The default <code>nginx-vhosts</code> proxy plugin supports both the <code>http</code> and <code>https</code> schemes.</li> </ul> </li> <li>Default port mappings<ul> <li>buildpack apps will be set to <code>http:80:5000</code> and will also include <code>https:443:5000</code> if SSL is enabled.</li> <li>dockerfile apps with explicitly exposed ports (i.e. using the <code>EXPOSE</code> directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container.<ul> <li>You may override this behavior with the <code>proxy:ports-*</code> commands or by directly setting <code>DOKKU_PROXY_PORT_MAP</code> with the <code>config:set</code> command</li> <li>dockerfile apps without explicitly exposed ports will behave the same as a buildpack app</li> </ul> </li> <li>NOTE: These defaults are not automatically changed on subsequent pushes and must be manipulated with the aforementioned commands</li> </ul> </li> </ul>"},{"location":"appendices/0.6.0-migration-guide/#calling-the-dokku-binary","title":"Calling the <code>dokku</code> binary","text":"<ul> <li>Plugins should not call the <code>dokku</code> binary directly. Clients using the <code>--app</code> argument are potentially broken, amongst others, when doing so. Instead, please source the <code>functions</code> file for a given plugin when attempting to call Dokku internal functions. As a result, the following Dokku commands are no longer publicly exposed:<ul> <li><code>dokku build</code></li> <li><code>dokku receive</code></li> <li><code>dokku release</code></li> <li><code>dokku tar:build</code></li> <li><code>dokku tar:build-locked</code></li> <li><code>dokku git:build</code></li> <li><code>dokku git:build-locked</code></li> </ul> </li> </ul>"},{"location":"appendices/0.7.0-migration-guide/","title":"0.7.0 Migration Guide","text":""},{"location":"appendices/0.7.0-migration-guide/#persistent-storage","title":"Persistent Storage","text":"<p>We should now properly handle file ownership for mounted directories. This was enhanced in 0.7.1. See the persistent storage documentation for more details.</p>"},{"location":"appendices/0.7.0-migration-guide/#restart-policies","title":"Restart Policies","text":"<p>If you previously managed container restart policies via docker-options, these can now be managed natively via the built-in <code>ps</code> plugin. There is no migration necessary. See the restart policy documentation for more details.</p>"},{"location":"appendices/0.7.0-migration-guide/#ssh-keys","title":"SSH Keys","text":"<p>Dokku now has an <code>ssh-keys</code> plugin that can be used to manage ssh keys for the <code>dokku</code> user on the host operating system. See the user management documentation for more details.</p>"},{"location":"appendices/0.8.0-migration-guide/","title":"0.8.0 Migration Guide","text":""},{"location":"appendices/0.8.0-migration-guide/#domain-management","title":"Domain Management","text":"<p>You can now set global and app domains via <code>domains:set</code> and <code>domains:set-global</code>. See the domains documentation for more details.</p>"},{"location":"appendices/0.8.0-migration-guide/#plugin-uninstallation","title":"Plugin Uninstallation","text":"<p>A new <code>uninstall</code> plugin trigger was introduced. This functionality may be in use for newer plugins, so be aware that older Dokku versions may require manual cleanup.</p> <p>See the uninstall trigger documentation for implementation instructions.</p>"},{"location":"appendices/0.8.0-migration-guide/#deployment-tasks","title":"Deployment Tasks","text":"<p>Should a pre or post deployment task fail, we now fail the entire deploy.</p>"},{"location":"appendices/0.8.0-migration-guide/#nginx-http2-support","title":"Nginx HTTP2 Support","text":"<p>Due to bugs in Nginx, the minimum version for HTTP2 is now 1.11.5.</p>"},{"location":"appendices/0.9.0-migration-guide/","title":"0.9.0 Migration Guide","text":""},{"location":"appendices/0.9.0-migration-guide/#golang-migration","title":"Golang Migration","text":"<p>There is an ongoing migration to rewrite Dokku in Golang. The reasons are beyond the scope of this document, but this may impact any patches you have for Dokku. As of 0.9.0, only the <code>repo</code> plugin is in Golang.</p> <p>The following shall remain true, regardless of the state of our rewrite:</p> <ul> <li>You will be able to write custom plugins in any language.</li> <li>You will be able to enable or disable core plugins.</li> <li><code>plugn</code> will continue to be used for executing plugin triggers.</li> <li>We will provide bash wrappers that can be sourced to execute core functionality that is implemented in golang.</li> </ul>"},{"location":"community/clients/","title":"Clients","text":"<p>Given the constraints, running Dokku commands remotely via SSH is fine. For certain configurations, the extra complication of manually invoking ssh can be a burden.</p> <p>The easiest way to interact with Dokku remotely is by using the official client. Documented below are the various clients that you may wish to use.</p>"},{"location":"community/clients/#official-client","title":"Official Client","text":"<p>See the remote commands documentation for more information on how to install and use the official client.</p>"},{"location":"community/clients/#nodejs-dokku-toolbelt","title":"(nodejs) dokku-toolbelt","text":"<p>Dokku-toolbelt is a node-based cli wrapper that proxies requests to the Dokku command running on remote hosts. You can install it via the following shell command (assuming you have nodejs and npm installed):</p> <pre><code>npm install -g dokku-toolbelt\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dokku-cli","title":"(ruby) Dokku CLI","text":"<p>Dokku CLI is a rubygem that acts as a client for your Dokku installation. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dokku-cli\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dokkuclient","title":"(ruby) DokkuClient","text":"<p>DokkuClient is another rubygem that acts as a client for your Dokku installation with built-in support for certain external plugins. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dokku_client\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dokkufy","title":"(ruby) Dokkufy","text":"<p>Dokkufy is a rubygem that handles automation of certain tasks, such as Dokku setup, plugin installation, etc. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dokkufy\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/clients/#ruby-dockland","title":"(ruby) Dockland","text":"<p>Dockland is a rubygem that acts as a client for your Dokku installation. You can install it via the following shell command (assuming you have ruby and rubygems installed):</p> <pre><code>gem install dockland\n</code></pre> <p>See documentation here for more information.</p>"},{"location":"community/plugins/","title":"Plugins","text":"<p>Dokku itself is built out of plugins and uses plugn for its plugin system. In essence a plugin is a collection of scripts that will be run based on naming convention.</p> <p>Let's take a quick look at the current Dokku nginx plugin that's shipped with Dokku by default.</p> <pre><code>nginx-vhosts/\n\u251c\u2500\u2500 plugin.toml  # plugin metadata\n\u251c\u2500\u2500 commands     # contains additional commands\n\u251c\u2500\u2500 install      # runs on Dokku installation\n\u2514\u2500\u2500 post-deploy  # runs after an app is deployed\n</code></pre>"},{"location":"community/plugins/#installing-a-plugin","title":"Installing a plugin","text":"<p>See the plugin management documentation.</p>"},{"location":"community/plugins/#creating-your-own-plugin","title":"Creating your own plugin","text":"<p>See the full documentation.</p>"},{"location":"community/plugins/#official-plugins","title":"Official Plugins","text":"<p>The following plugins are available and provided by Dokku maintainers.  Please file issues against their respective issue trackers.</p> Plugin Author Compatibility Clickhouse dokku 0.4.0+ Copy Files to Image dokku 0.4.0+ CouchDB dokku 0.4.0+ Cron Restart dokku 0.30.0+ Elasticsearch dokku 0.4.0+ Grafana/Graphite/Statsd dokku 0.4.0+ HTTP Auth dokku 0.4.0+ Let's Encrypt dokku 0.4.0+ Maintenance mode dokku 0.4.0+ MariaDB dokku 0.4.0+ Meilisearch dokku 0.4.0+ Memcached dokku 0.4.0+ Mongo dokku 0.4.0+ MySQL dokku 0.4.0+ Nats dokku 0.4.0+ Omnisci dokku 0.4.0+ Postgres dokku 0.4.0+ Pushpin dokku 0.4.0+ RabbitMQ dokku 0.4.0+ Redirect dokku 0.4.0+ Redis dokku 0.4.0+ Registry dokku 0.12.0+ RethinkDB dokku 0.4.0+ Scheduler Kubernetes dokku 0.4.0+ Scheduler Nomad dokku 0.4.0+ Solr dokku 0.4.0+ SSH Hostkeys dokku 0.4.0+ Typesense dokku 0.4.0+"},{"location":"community/plugins/#community-plugins","title":"Community plugins","text":"<p>Warning</p> <p>The following plugins have been supplied by our community and may not have been tested by Dokku maintainers.</p>"},{"location":"community/plugins/#datastores","title":"Datastores","text":""},{"location":"community/plugins/#relational","title":"Relational","text":"Plugin Author Compatibility MariaDB kloadut 0.3.x MariaDB (single container) ohardy 0.3.x MariaDB (single container) krisrang 0.3.26+ PostgreSQL jlachowski 0.3.x PostgreSQL (single container) ohardy 0.3.x PostgreSQL (single container) flink 0.3.26+ Edgedb ignisda 0.27.0+"},{"location":"community/plugins/#newsql","title":"NewSQL","text":"Plugin Author Compatibility Surrealdb ignisda 0.27.0+"},{"location":"community/plugins/#caching","title":"Caching","text":"Plugin Author Compatibility Nginx Cache aluxian 0.5.0+ Redis (single container) ohardy 0.3.x Varnish zenedith Varnish cache between nginx and application with base configuration"},{"location":"community/plugins/#queuing","title":"Queuing","text":"Plugin Author Compatibility RabbitMQ jlachowski 0.3.x RabbitMQ (single container) jlachowski 0.3.x ElasticMQ (SQS compatible) cu12 0.5.0+ VerneMQ (MQTT Broker) mrname 0.4.0+"},{"location":"community/plugins/#other","title":"Other","text":"Plugin Author Compatibility etcd basgys 0.4.x FakeSNS cu12 0.5.0+ InfluxDB basgys 0.4.x RethinkDB stuartpb 0.3.x Headless Chrome lazyatom 0.8.1+"},{"location":"community/plugins/#plugins-implementing-new-dokku-functionality","title":"Plugins Implementing New Dokku Functionality","text":"Plugin Author Compatibility App name as env cjblomqvist 0.3.x APT dokku-community 0.18.x+ Auto Sync<sup>1</sup> fomojola 0.8.1+ Deploy Webhook<sup>2</sup> fomojola 0.8.1+ Docker auto persist volumes flink 0.4.0+ Docker Direct josegonzalez 0.4.0+ Dokku Clone crisward 0.4.0+ Dokku Copy App Config Files josegonzalez 0.4.0+ Dokku Require<sup>3</sup> crisward 0.4.0+ Global Certificates josegonzalez 0.5.0+ Graduate (Environment Management) benjamin-dobell 0.4.0+ Host post-build command hook baikunz 0.4.0+ Host pre-build command hook fteychene 0.4.0+ Hostname michaelshobbs 0.4.0+ Hostname michaelshobbs 0.4.0+ HTTP Auth Secure Apps matto1990 0.4.0+ Litestream<sup>4</sup> AxelTheGerman 0.27.0+ Monit (Health Checks) mbreit 0.8.0+ Monit cjblomqvist 0.3.x Nuke Containers josegonzalez 0.4.0+ Proctype Filter michaelshobbs 0.4.0+ robots.txt candlewaster 0.4.x Tor michaelshobbs 0.4.0+ UFW josegonzalez 0.3.x User Access mainto 0.4.0+ User ACL maciej \u0142ebkowski 0.4.0+ <p><sup>1</sup> Adds the ability to sync an application repo with a remote GitHub repo (useful for automated rebuilds without needing a git push from an external system</p> <p><sup>2</sup> Adds the ability to invoke a post-deploy webhook with the IP, port and app name, all with a single config:set).</p> <p><sup>3</sup> Extends app.json support to include creating volumes and creating / linking databases on push</p> <p><sup>4</sup> Adds SQLite replication to external object storage via Litestream</p>"},{"location":"community/plugins/#other-plugins","title":"Other Plugins","text":"Plugin Author Compatibility Chef cookbook nickcharlton Discourse badsyntax 0.21.4+ Wordpress dokku-community 0.4.0+"},{"location":"community/plugins/#deprecated-plugins","title":"Deprecated Plugins","text":"<p>The following plugins have been removed as their functionality is now in Dokku Core.</p> Plugin Author In Dokku Since Airbrake deploy flink v0.5.0 (deployment tasks) App User michaelshobbs v0.7.1 (herokuish 0.3.18) Bower/Grunt thrashr888 v0.5.0 (deployment tasks and .buildpacks) Bower/Gulp gdi2290 v0.5.0 (deployment tasks and .buildpacks) Bower install alexanderbeletsky v0.5.0 (deployment tasks and .buildpacks) Bower/Gulp jagandecapri v0.5.0 (deployment tasks and .buildpacks) Builders: bower, compass, gulp, grunt ignlg v0.5.0 (deployment tasks and .buildpacks) Custom Domains neam v0.3.10 (domains plugin) Debug josegonzalez v0.3.9 (trace command) Dockerfile custom path mimischi v0.25.0 (monorepo support) Docker Options dyson v0.3.17 (docker-options plugin) Dokku Name alex-sherwin v0.4.2 (named containers plugin) Events Logger alessio v0.3.21 (events plugin) Fonts ollej v0.5.0 (deployment tasks) git rev-parse HEAD in env cjblomqvist v0.12.0 (enhanced core git plugin) Host Port binding stuartpb v0.3.17 (docker-options plugin) Link Containers rlaneve v0.3.17 (docker-options plugin) List Containers josegonzalez v0.3.14 (ps plugin) Logspout michaelshobbs v0.22.6 (vector log shipping) Long Timeout investtools v0.21.0 (proxy-read-timeout nginx setting) Monorepo iamale v0.25.0 (monorepo builder support) Multi-Buildpack pauldub v0.4.0 (herokuish) Multiple Domains<sup>1</sup> wmluke v0.3.10 (domains plugin) Multi Dockerfile artofrawr v0.25.0 (monorepo support) Named-containers flink v0.4.2 (named-containers plugin) Nginx Trust Proxy kingsquare v0.23.0 (nginx x-forwarded-* properties) Node ademuk v0.5.0 (deployment tasks and .buildpacks) Node pnegahdar v0.5.0 (deployment tasks and .buildpacks) Nginx-Alt mikexstudios v0.3.10 (domains plugin) Persistent Storage dyson v0.3.17 (docker-options plugin) Pre-Deploy Tasks michaelshobbs v0.5.0 (deployment tasks) PrimeCache darkpixel v0.3.0 (zero downtime deploys) Rollbar iloveitaly v0.5.0 (deployment tasks) Syslog michaelshobbs v0.22.6 (vector log shipping) Haproxy tcp load balancer 256dpi v0.28.0 (haproxt plugin) Process Manager: Circus apmorton v0.3.14/0.7.0 (ps/restart policy plugin) Process Manager: Forego flink v0.3.14/0.7.0 (ps plugin) Process Manager: Forego iskandar v0.3.14/0.7.0 (ps plugin) Process Manager: Logging Supervisord sehrope v0.3.14/0.7.0 (ps plugin) Process Manager: Shoreman statianzo v0.3.14/0.7.0 (ps plugin) Process Manager: Supervisord statianzo v0.3.14/0.7.0 (ps plugin) Rebuild application scottatron v0.3.14 (ps plugin) Reset mtime mixxorz Docker 1.8+ SSH Deployment Keys dokku v0.33.0 (git plugin) Supply env vars to buildpacks<sup>2</sup> cameron-martin v0.3.9 (build-env plugin) Slack Notifications ribot v0.5.0 (deployment tasks) Telegram Notifications m0rth1um v0.5.0 (deployment tasks) user-env-compile<sup>2</sup> motin v0.3.9 (build-env plugin) user-env-compile<sup>2</sup> musicglue v0.3.9 (build-env plugin) Volume (persistent storage) ohardy v0.5.0 (storage plugin) Webhooks nickstenning v0.5.0 (deployment tasks) Wkhtmltopdf mbriskar v0.5.0 (deployment tasks) <p><sup>1</sup> Conflicts with VHOSTS Custom Configuration <sup>2</sup> Similar to the heroku-labs feature</p>"},{"location":"community/plugins/#unmaintained-plugins","title":"Unmaintained Plugins","text":"<p>The following plugins are no longer maintained by their developers.</p> Plugin Author Compatibility app-url mikecsh Works with 0.2.0 Chef cookbooks fgrehm CouchDB (multi containers) flink 0.4.0+ CouchDB raceHub Compatible with 0.2.0 Dokku Copy App Config Files alexkruegger Compatible with 0.3.17+ Dokku Registry agco-adm 0.4.0+ Elasticsearch robv Not compatible with &gt;= 0.3.0 (still uses /home/git) Elasticsearch<sup>1</sup> blag Compatible with 0.2.0 Graphite/statsd jlachowski &lt; 0.4.0 HipChat Notifications cef Memcached flink 0.4.0+ MongoDB (single container) jeffutter MySQL hughfletcher Neo4j aomitayo PostGIS fermuch PostgreSQL (single container) jeffutter This plugin creates a single postgresql container that all your apps can use. Thus only one instance of postgresql running (good for servers without a ton of memory). Redis luxifer Redis sekjun9878 0.3.26+ RiakCS (single container) jeffutter Incompatible with 0.2.0 <p><sup>1</sup> Forked from jezdez/dokku-elasticsearch-plugin: uses Elasticsearch 1.2 (instead of 0.90), doesn't depend on dokku-link, runs as elasticsearch user instead of root, and turns off multicast autodiscovery for use in a VPS environment.</p>"},{"location":"configuration/domains/","title":"Domain Configuration","text":"<p>New</p> <p>Introduced in 0.3.10</p> <pre><code>domains:add &lt;app&gt; &lt;domain&gt; [&lt;domain&gt; ...]      # Add domains to app\ndomains:add-global &lt;domain&gt; [&lt;domain&gt; ...]     # Add global domain names\ndomains:clear &lt;app&gt;                            # Clear all domains for app\ndomains:clear-global                           # Clear global domain names\ndomains:disable &lt;app&gt;                          # Disable VHOST support\ndomains:enable &lt;app&gt;                           # Enable VHOST support\ndomains:remove &lt;app&gt; &lt;domain&gt; [&lt;domain&gt; ...]   # Remove domains from app\ndomains:remove-global &lt;domain&gt; [&lt;domain&gt; ...]  # Remove global domain names\ndomains:report [&lt;app&gt;|--global] [&lt;flag&gt;]       # Displays a domains report for one or more apps\ndomains:set &lt;app&gt; &lt;domain&gt; [&lt;domain&gt; ...]      # Set domains for app\ndomains:set-global &lt;domain&gt; [&lt;domain&gt; ...]     # Set global domain names\n</code></pre> <p>Info</p> <p>Adding a domain before deploying an application will result in port mappings being set. This may cause issues for applications that use non-standard ports, as those will not be automatically detected. Please refer to the proxy documentation for information as to how to reconfigure the mappings.</p>"},{"location":"configuration/domains/#customizing-hostnames","title":"Customizing hostnames","text":"<p>Applications typically have the following structure for their hostname:</p> <pre><code>scheme://subdomain.domain.tld\n</code></pre> <p>The <code>subdomain</code> is inferred from the pushed application name, while the <code>domain.tld</code> is set during initial dokku configuration. It can then be modified with <code>dokku domains:add-global</code> and <code>dokku domains:remove-global</code>. This value is used as a default TLD for all applications on a host.</p> <p>If an FQDN such as <code>dokku.org</code> is used as the application name, the global virtualhost will be ignored and the resulting vhost URL for that application will be <code>dokku.org</code>.</p> <p>You can optionally override this in a plugin by implementing the <code>nginx-hostname</code> plugin trigger. If the <code>nginx-hostname</code> plugin has no output, the normal hostname algorithm will be executed. See the plugin trigger documentation for more information.</p>"},{"location":"configuration/domains/#disabling-vhosts","title":"Disabling VHOSTS","text":"<p>If desired, it is possible to disable vhosts with the domains plugin.</p> <pre><code>dokku domains:disable node-js-app\n</code></pre> <p>On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting <code>DOKKU_PROXY_PORT</code> and/or <code>DOKKU_PROXY_SSL_PORT</code> (for services configured to use SSL.)</p> <p>The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via <code>certs:add</code>. Be aware that disabling domains (with <code>domains:disable</code>) will override any custom domains.</p> <pre><code># where `node-js-app` is the name of your app\n\n# add a domain to an app\ndokku domains:add node-js-app dokku.me\n\n# list custom domains for app\ndokku domains:report node-js-app\n\n# clear all custom domains for app\ndokku domains:clear node-js-app\n\n# remove a custom domain from app\ndokku domains:remove node-js-app dokku.me\n\n# set all custom domains for app\ndokku domains:set node-js-app dokku.me dokku.org\n</code></pre>"},{"location":"configuration/domains/#displaying-domains-reports-for-an-app","title":"Displaying domains reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's domains status using the <code>domains:report</code> command:</p> ShellOutput <pre><code>dokku domains:report\n</code></pre> <pre><code>=====&gt; node-js-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  node-js-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n=====&gt; python-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  python-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n=====&gt; ruby-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  ruby-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku domains:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app domains information\n       Domains app enabled: true\n       Domains app vhosts:  node-js-app.dokku.org\n       Domains global enabled: true\n       Domains global vhosts: dokku.org\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku domains:report node-js-app --domains-app-enabled\n</code></pre>"},{"location":"configuration/domains/#default-site","title":"Default site","text":"<p>This is specific to your proxy plugin of choice. See the nginx documentation for more information on how to configure this for the default nginx proxy implementation.</p>"},{"location":"configuration/environment-variables/","title":"Environment Variables","text":"<p>Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommended to store them in your application's repository.</p> <p>The <code>config</code> plugin provides the following commands to manage your variables:</p> <pre><code>config:show (&lt;app&gt;|--global)                                                          Pretty-print an app or global environment\nconfig:bundle (&lt;app&gt;|--global) [--merged]                                             Bundle environment into tarfile\nconfig:clear (&lt;app&gt;|--global)                                                         Clears environment variables\nconfig:export (&lt;app&gt;|--global) [--envfile]                                            Export a global or app environment\nconfig:get (&lt;app&gt;|--global) KEY                                                       Display a global or app-specific config value\nconfig:keys (&lt;app&gt;|--global) [--merged]                                               Show keys set in environment\nconfig:set [--encoded] [--no-restart] (&lt;app&gt;|--global) KEY1=VALUE1 [KEY2=VALUE2 ...]  Set one or more config vars\nconfig:unset [--no-restart] (&lt;app&gt;|--global) KEY1 [KEY2 ...]                          Unset one or more config vars\n</code></pre> <p>Info</p> <p>For security reasons - and as per docker recommendations - Dockerfile-based deploys have variables available only during runtime, as noted in this issue. Consider using build arguments to expose variables during build-time for Dockerfile apps.</p> <p>Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys.</p> <p>For buildpack deploys, Dokku will create a  <code>/app/.env</code> file that can be used for legacy buildpacks. Note that this is not updated when <code>config:set</code> or <code>config:unset</code> is called, and is only written during a <code>deploy</code> or <code>ps:rebuild</code>. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.</p> <p>Note</p> <p>Global <code>ENV</code> files are sourced before app-specific <code>ENV</code> files. This means that app-specific variables will take precedence over global variables. Configuring your global <code>ENV</code> file is manual, and should be considered potentially dangerous as configuration applies to all applications.</p> <p>You can set multiple environment variables at once:</p> <pre><code>dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1\n</code></pre> <p>Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:</p> <pre><code>dokku config:set node-js-app KEY=\"VAL\\ WITH\\ SPACES\"\n</code></pre> <p>Dokku can also read base64 encoded values. That's the easiest way to set a value with newlines or spaces. To set a value with newlines you need to base64 encode it first and pass the <code>--encoded</code> flag:</p> <pre><code>dokku config:set --encoded node-js-app KEY=\"$(base64 ~/.ssh/id_rsa)\"\n</code></pre> <p>When setting or unsetting environment variables, you may wish to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the <code>--no-restart</code> flag:</p> <pre><code>dokku config:set --no-restart node-js-app ENV=prod\n</code></pre> <p>If you wish to have the variables output in an <code>eval</code>-compatible form, you can use the <code>config:export</code> command</p> <pre><code>dokku config:export node-js-app\n# outputs variables in the form:\n#\n#   export ENV='prod'\n#   export COMPILE_ASSETS='1'\n\n# source in all the node-js-app app environment variables\neval $(dokku config:export node-js-app)\n</code></pre> <p>You can control the format of the exported variables with the <code>--format</code> flag. <code>--format=shell</code> will output the variables in a single-line for usage in command-line utilities:</p> <pre><code>dokku config:export --format shell node-js-app\n\n# outputs variables in the form:\n#\n#   ENV='prod' COMPILE_ASSETS='1'\n</code></pre>"},{"location":"configuration/environment-variables/#special-config-variables","title":"Special Config Variables","text":"<p>The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future.</p> <p>Warning</p> <p>This list is not exhaustive, and may vary from version to version.</p> Name Default How to modify Description <code>DOKKU_ROOT</code> <code>~dokku</code> <code>/etc/environment</code> The root directory where dokku will store application repositories, as well as certain configuration files. <code>DOKKU_IMAGE</code> <code>gliderlabs/herokuish</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The default image to use when building herokuish containers. Deprecated in favor of using <code>buildpacks:set-property</code> <code>DOKKU_LIB_ROOT</code> <code>/var/lib/dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory where plugins, certain data, and general configuration is stored. <code>PLUGIN_PATH</code> <code>$DOKKU_LIB_ROOT/plugins\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The top-level directory where plugins are stored. <code>PLUGIN_AVAILABLE_PATH</code> <code>$PLUGIN_PATH/available\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that holds all available plugins, including core. <code>PLUGIN_ENABLED_PATH</code> <code>$PLUGIN_PATH/enabled\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that holds all enabled plugins, including core. <code>PLUGIN_CORE_PATH</code> <code>$DOKKU_LIB_ROOT/core-plugins\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that stores all core plugins. <code>PLUGIN_CORE_AVAILABLE_PATH</code> <code>$PLUGIN_CORE_PATH/available\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that stores all available core plugins. <code>PLUGIN_CORE_ENABLED_PATH</code> <code>$PLUGIN_CORE_PATH/enabled\"</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> The directory that stores all enabled core plugins. <code>DOKKU_LOGS_DIR</code> <code>/var/log/dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Where dokku logs should be written to. <code>DOKKU_LOGS_HOST_DIR</code> <code>$DOKKU_LOGS_DIR</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> A path on the host that will be mounted into the vector logging container. <code>DOKKU_EVENTS_LOGFILE</code> <code>$DOKKU_LOGS_DIR/events.log</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Where the events log file is written to. <code>DOKKU_APP_NAME</code> none <code>--app APP</code> flag Name of application to work on. Respected by core plugins. <code>DOKKU_APPS_FORCE_DELETE</code> none <code>--force</code> flag Whether to force delete an application. Also used by other plugins for destructive actions. <code>DOKKU_CHECKS_URL</code> <code>https://dokku.com/docs/deployment/zero-downtime-deploys/</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Url displayed during deployment when no CHECKS file exists. <code>DOKKU_QUIET_OUTPUT</code> none <code>--quiet</code> flag Silences certain header output for <code>dokku</code> commands. <code>DOKKU_RM_CONTAINER</code> none <code>dokku config:set</code> Deprecated: Whether to keep <code>dokku run</code> containers around or not. <code>DOKKU_TRACE</code> none <code>dokku trace:on</code> <code>dokku trace:off</code> <code>--trace</code> flag Turn on very verbose debugging. <code>DOKKU_APP_PROXY_TYPE</code> <code>nginx</code> <code>dokku proxy:set</code> <code>DOKKU_APP_RESTORE</code> <code>1</code> <code>dokku config:set</code> <code>dokku ps:stop</code> <code>DOKKU_APP_SHELL</code> <code>/bin/bash</code> <code>dokku config:set</code> Allows users to change the default shell used by Dokku for <code>dokku enter</code> and execution of deployment tasks. <code>DOKKU_APP_TYPE</code> <code>herokuish</code> Auto-detected by using buildpacks or dockerfile <code>DOKKU_CHECKS_DISABLED</code> none <code>dokku checks:disable</code> <code>DOKKU_CHECKS_ENABLED</code> none <code>dokku checks:enable</code> <code>DOKKU_CHECKS_SKIPPED</code> none <code>dokku checks:skip</code> <code>DOKKU_CHECKS_WAIT</code> <code>5</code> <code>dokku config:set</code> Wait this many seconds for the container to start before running checks. <code>DOKKU_CHECKS_TIMEOUT</code> <code>30</code> <code>dokku config:set</code> Wait this many seconds for each response before marking it as a failure. <code>DOKKU_CHECKS_ATTEMPTS</code> <code>5</code> <code>dokku config:set</code> Number of retries for to run for a specific check before marking it as a failure <code>DOKKU_DEFAULT_CHECKS_WAIT</code> <code>10</code> <code>dokku config:set</code> If no user-defined checks are specified - or if the process being checked is not a <code>web</code> process - this is the period of time Dokku will wait before checking that a container is still running. <code>DOKKU_DISABLE_PROXY</code> none <code>dokku proxy:disable</code> <code>dokku proxy:enable</code> Disables the proxy in front of your application, resulting in publicly routing the docker container. <code>DOKKU_DISABLE_ANSI_PREFIX_REMOVAL</code> none <code>dokku config:set</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> Disables removal of the ANSI prefix during deploys. Can be used in cases where the client deployer does not understand ansi escape  codes. <code>DOKKU_DISABLE_APP_AUTOCREATION</code> none <code>dokku config:set</code> Disables automatic creation of a non-existent app on deploy. <code>DOKKU_DOCKER_STOP_TIMEOUT</code> <code>10</code> <code>dokku config:set</code> Configurable grace period given to the <code>docker stop</code> command. If a container has not stopped by this time, a <code>kill -9</code> signal or equivalent is sent in order to force-terminate the container. Both the <code>ps:stop</code> and <code>apps:destroy</code> commands also respect this value. If not specified, the docker defaults for the docker stop command will be used. <code>DOKKU_DOCKERFILE_CACHE_BUILD</code> none <code>dokku config:set</code> <code>DOKKU_DOCKERFILE_START_CMD</code> none <code>dokku config:set</code> <code>DOKKU_PARALLEL_ARGUMENTS</code>. none <code>dokku config:set</code> Allows passing custom arguments to parallel for <code>ps:*all</code> commands <code>DOKKU_PROXY_PORT</code> automatically assigned <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> <code>dokku config:set</code> <code>DOKKU_PROXY_SSL_PORT</code> automatically assigned <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> <code>dokku config:set</code> <code>DOKKU_SKIP_ALL_CHECKS</code> none <code>dokku config:set</code> <code>DOKKU_SKIP_CLEANUP</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. <code>DOKKU_SKIP_DEFAULT_CHECKS</code> <code>dokku config:set</code> <code>DOKKU_SKIP_DEPLOY</code> <code>dokku config:set</code> <code>DOKKU_START_CMD</code> none <code>dokku config:set</code> Command to run instead of <code>/start $PROC_TYPE</code> <code>DOKKU_SYSTEM_GROUP</code> <code>dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> System group to chown files as. <code>DOKKU_SYSTEM_USER</code> <code>dokku</code> <code>/etc/environment</code> <code>~dokku/.dokkurc</code> <code>~dokku/.dokkurc/*</code> System user to chown files as."},{"location":"configuration/ssl/","title":"SSL Configuration","text":"<p>New</p> <p>Introduced in 0.4.0</p> <p>Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the <code>certs</code> plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled.</p> <pre><code>certs:add &lt;app&gt; CRT KEY                  # Add an ssl endpoint to an app. Can also import from a tarball on stdin.\ncerts:generate &lt;app&gt; DOMAIN              # Generate a key and certificate signing request (and self-signed certificate)\ncerts:remove &lt;app&gt;                       # Remove an SSL Endpoint from an app.\ncerts:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays an ssl report for one or more apps\ncerts:show &lt;app&gt; &lt;crt|key&gt;               # Show the server.crt or server.key on stdout\ncerts:update &lt;app&gt; CRT KEY               # Update an SSL Endpoint on an app. Can also import from a tarball on stdin\n</code></pre> <pre><code># for 0.3.x\ndokku nginx:import-ssl &lt;app&gt; &lt; certs.tar\n</code></pre> <p>Info</p> <p>Adding an ssl certificate before deploying an application will result in port mappings being updated. This may cause issues for applications that use non-standard ports, as those may not be automatically detected. Please refer to the proxy documentation for information as to how to reconfigure the mappings.</p>"},{"location":"configuration/ssl/#per-application-certificate-management","title":"Per-application certificate management","text":"<p>Dokku provides built-in support for managing SSL certificates on a per-application basis. SSL is managed via nginx outside of application containers, and as such can be updated on-the-fly without rebuilding containers. At this time, applications only support a single SSL certificate at a time. To support multiple domains for a single application, wildcard certificate usage is encouraged.</p>"},{"location":"configuration/ssl/#certificate-setting","title":"Certificate setting","text":"<p>The <code>certs:add</code> command can be used to push a <code>tar</code> containing a certificate <code>.crt</code> and <code>.key</code> file to a single application. The command should correctly handle cases where the <code>.crt</code> and <code>.key</code> are not named properly or are nested in a subdirectory of said <code>tar</code> file. You can import it as follows:</p> <pre><code>tar cvf cert-key.tar server.crt server.key\ndokku certs:add node-js-app &lt; cert-key.tar\n</code></pre> <p>Note</p> <p>If your <code>.crt</code> file came alongside a <code>.ca-bundle</code>, you'll want to concatenate those into a single <code>.crt</code> file before adding it to the <code>.tar</code>.</p> <pre><code>cat yourdomain_com.crt yourdomain_com.ca-bundle &gt; server.crt\n</code></pre>"},{"location":"configuration/ssl/#ssl-and-multiple-domains","title":"SSL and Multiple Domains","text":"<p>When an SSL certificate is associated to an application, the certificate will be associated with all domains currently associated with said application. Your certificate should be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the domain configuration documentation.</p> <p>Note that with the default nginx template, requests will be redirected to the <code>https</code> version of the domain. If this is not the desired state of request resolution, you may customize the nginx template in use. For more details, see the nginx documentation.</p>"},{"location":"configuration/ssl/#certificate-generation","title":"Certificate generation","text":"<p>Note</p> <p>Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.</p> <p>The <code>certs:generate</code> command will walk you through the correct <code>openssl</code> commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration.</p> <p>If you decide to obtain a CA signed certificate, you can import that certificate using the aforementioned <code>dokku certs:add</code> command.</p>"},{"location":"configuration/ssl/#certificate-removal","title":"Certificate removal","text":"<p>The <code>certs:remove</code> command only works on app-specific certificates. It will <code>rm</code> the app-specific tls directory, rebuild the nginx configuration, and reload nginx.</p>"},{"location":"configuration/ssl/#showing-the-certificate","title":"Showing the certificate","text":"<p>The <code>certs:show</code> command can be used to show your configured certs for an app. The show command can be used for example to export Let's Encrypt certificates after they've been generated. You can export it as follows:</p> <pre><code>dokku certs:show node-js-app crt &gt; server.crt\ndokku certs:show node-js-app key &gt; server.key\n</code></pre>"},{"location":"configuration/ssl/#displaying-certificate-reports-for-an-app","title":"Displaying certificate reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the apps ssl status using the <code>certs:report</code> command:</p> ShellOutput <pre><code>dokku certs:report\n</code></pre> <pre><code>=====&gt; node-js-app\n       Ssl dir:             /home/dokku/node-js-app/tls\n       Ssl enabled:         true\n       Ssl hostnames:       *.node-js-app.org node-js-app.org\n       Ssl expires at:      Oct  5 23:59:59 2019 GMT\n       Ssl issuer:          C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Domain Validation Secure Server CA\n       Ssl starts at:       Oct  5 00:00:00 2016 GMT\n       Ssl subject:         OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.node-js-app.org\n       Ssl verified:        self signed.\n=====&gt; python-app\n       Ssl dir:             /home/dokku/python-app/tls\n       Ssl enabled:         false\n       Ssl hostnames:\n       Ssl expires at:\n       Ssl issuer:\n       Ssl starts at:\n       Ssl subject:\n       Ssl verified:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku certs:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app ssl information\n       Ssl dir:             /home/dokku/node-js-app/tls\n       Ssl enabled:         true\n       Ssl hostnames:       *.dokku.org dokku.org\n       Ssl expires at:      Oct  5 23:59:59 2019 GMT\n       Ssl issuer:          C=GB, ST=Greater Manchester, L=Salford, O=COMODO CA Limited, CN=COMODO RSA Domain Validation Secure Server CA\n       Ssl starts at:       Oct  5 00:00:00 2016 GMT\n       Ssl subject:         OU=Domain Control Validated; OU=PositiveSSL Wildcard; CN=*.dokku.org\n       Ssl verified:        self signed.\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku certs:report node-js-app --ssl-enabled\n</code></pre>"},{"location":"configuration/ssl/#hsts-header","title":"HSTS Header","text":"<p>The HSTS header is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. Dokku does enables this header by default for HTTPS requests.</p> <p>See the NGINX HSTS documentation for more information on how the HSTS configuration can be managed for your application.</p>"},{"location":"configuration/ssl/#http2-support","title":"HTTP/2 support","text":"<p>Certain versions of nginx have bugs that prevent HTTP/2 from properly responding to all clients, thus causing applications to be unavailable. For HTTP/2 to be enabled in your applications' nginx configs, you need to have installed nginx 1.11.5 or higher. See issue 2435 for more details.</p>"},{"location":"configuration/ssl/#ssl-port-exposure","title":"SSL Port Exposure","text":"<p>When your app is served from port <code>80</code> then the <code>/home/dokku/APP/nginx.conf</code> file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port <code>99999</code>) you may need to manually expose an ssl port via <code>dokku ports:add &lt;APP&gt; https:443:99999</code>.</p>"},{"location":"configuration/ssl/#other","title":"Other","text":""},{"location":"configuration/ssl/#running-behind-a-proxy-x-forwarded-ssl-etc","title":"Running behind a proxy (<code>X-Forwarded-Ssl</code>, etc.)","text":"<p>See the running behind another proxy documentation for more information on how to configure your Nginx config when your server is running behind a proxy (e.g. load balancer, etc.).</p>"},{"location":"deployment/application-deployment/","title":"Deploying an Application","text":"<p>Note</p> <p>This walkthrough uses the hostname <code>dokku.me</code> in commands. When deploying to your own server, you should substitute the domain <code>dokku.me</code> for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use <code>dokku.me</code> which points to the IP of the VM.</p>"},{"location":"deployment/application-deployment/#deploy-tutorial","title":"Deploy tutorial","text":"<p>Once you have configured Dokku with at least one user, you can deploy applications using <code>git push</code>. To quickly see Dokku deployment in action, try using the Heroku Ruby on Rails \"Getting Started\" app.</p> <pre><code># from your local machine\ngit clone https://github.com/heroku/ruby-getting-started\n</code></pre>"},{"location":"deployment/application-deployment/#create-the-app","title":"Create the app","text":"<p>SSH into the Dokku host and create the application as follows:</p> <pre><code># on the Dokku host\ndokku apps:create ruby-getting-started\n</code></pre>"},{"location":"deployment/application-deployment/#create-the-backing-services","title":"Create the backing services","text":"<p>Dokku by default does not provide datastores (e.g. MySQL, PostgreSQL) on a newly created app. You can add datastore support by installing plugins, and the Dokku project provides official plugins for common datastores.</p> <p>The Getting Started app requires a PostgreSQL service, so install the plugin and create the related service as follows:</p> <pre><code># on the Dokku host\n# install the postgres plugin\n# plugin installation requires root, hence the user change\nsudo dokku plugin:install https://github.com/dokku/dokku-postgres.git\n\n# create a postgres service with the name railsdatabase\ndokku postgres:create railsdatabase\n</code></pre> <p>Each service may take a few moments to create.</p>"},{"location":"deployment/application-deployment/#linking-backing-services-to-applications","title":"Linking backing services to applications","text":"<p>Once the services have been created, you then set the <code>DATABASE_URL</code> environment variable by linking the service, as follows:</p> <pre><code># on the Dokku host\n# each official datastore offers a `link` method to link a service to any application\ndokku postgres:link railsdatabase ruby-getting-started\n</code></pre> <p>Dokku supports linking a single service to multiple applications as well as linking only one service per application.</p>"},{"location":"deployment/application-deployment/#deploy-the-app","title":"Deploy the app","text":"<p>Warning</p> <p>Your app should respect the <code>PORT</code> environment variable, otherwise it may not respond to web requests. You can find more information in the port management documentation.**</p> <p>Now you can deploy the <code>ruby-getting-started</code> app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.</p> <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\ncd ruby-getting-started\ngit remote add dokku dokku@dokku.me:ruby-getting-started\ngit push dokku main\n</code></pre> <p>Note</p> <p>Some tools may not support the short-upstream syntax referenced above, and you may need to prefix the upstream with the scheme <code>ssh://</code> like so: <code>ssh://dokku@dokku.me:ruby-getting-started</code> Please see the Git documentation for more details.</p> <p>Note</p> <p>Your private key should be registered with <code>ssh-agent</code> in your local development environment. If you get a <code>permission denied</code> error when pushing, you can register your private key as follows: <code>ssh-add -k ~/&lt;your private key&gt;</code>.</p> <p>After running <code>git push dokku main</code>, you should have output similar to this in your terminal:</p> <pre><code>Counting objects: 231, done.\nDelta compression using up to 8 threads.\nCompressing objects: 100% (162/162), done.\nWriting objects: 100% (231/231), 36.96 KiB | 0 bytes/s, done.\nTotal 231 (delta 93), reused 147 (delta 53)\n-----&gt; Cleaning up...\n-----&gt; Building ruby-getting-started from herokuish...\n-----&gt; Adding BUILD_ENV to build environment...\n-----&gt; Ruby app detected\n-----&gt; Compiling Ruby/Rails\n-----&gt; Using Ruby version: ruby-2.2.1\n-----&gt; Installing dependencies using 1.9.7\n       Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment\n       Fetching gem metadata from https://rubygems.org/...........\n       Fetching version metadata from https://rubygems.org/...\n       Fetching dependency metadata from https://rubygems.org/..\n       Using rake 10.4.2\n\n...\n\n=====&gt; Application deployed:\n       http://ruby-getting-started.dokku.me\n</code></pre> <p>Once the deploy is complete, the application's web URL will be generated as above.</p> <p>Dokku supports deploying applications in a few ways:</p> <ul> <li>Heroku buildpacks via Herokuish: See the herokuish buildpacks documentation to learn about the different ways to specify a buildpack.<ul> <li>This is the default method used by Dokku.</li> </ul> </li> <li>Dockerfile: See the dockerfile documentation to learn about the different ways to configure Dockerfile-based deploys.</li> <li>Docker Image: See the docker image documentation to learn about how to deploy a Docker Image.</li> </ul>"},{"location":"deployment/application-deployment/#setting-up-ssl","title":"Setting up SSL","text":"<p>Info</p> <p>While SSL certificates can be imported, automated SSL via Letsencrypt requires that all domains on an app correctly point at your server's public ip address. Please keep this in mind when using Letsencrypt.</p> <p>For many users, responding to requests via <code>https</code> will be desirable. Dokku has a complete ssl plugin built in that can be used to import SSL certificates (below is a short example, please refer to the ssl documentation for more information):</p> <pre><code>dokku certs:add ruby-getting-started server.crt server.key\n</code></pre> <p>As an alternative, the Dokku project offers an optional letsencrypt plugin that can be used to automate SSL certificate retrieval and renewal.</p> <pre><code># on the Dokku host\n# install the letsencrypt plugin\n# plugin installation requires root, hence the user change\nsudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git\n\n# set global email for letsencrypt\ndokku letsencrypt:set --global email your-email@your.domain.com\n\n# set a custom domain that you own for your application\ndokku domains:set ruby-getting-started ruby-getting-started.your.domain.com\n\n# enable letsencrypt\ndokku letsencrypt:enable ruby-getting-started\n\n# enable auto-renewal\ndokku letsencrypt:cron-job --add\n</code></pre>"},{"location":"deployment/application-deployment/#skipping-deployment","title":"Skipping deployment","text":"<p>If you only want to rebuild and tag a container, you can skip the deployment phase by setting <code>$DOKKU_SKIP_DEPLOY</code> to <code>true</code> by running:</p> <pre><code># on the Dokku host\ndokku config:set ruby-getting-started DOKKU_SKIP_DEPLOY=true\n</code></pre>"},{"location":"deployment/application-deployment/#redeploying-or-restarting","title":"Redeploying or restarting","text":"<p>If you need to redeploy or restart your app:</p> <pre><code># on the Dokku host\ndokku ps:rebuild ruby-getting-started\n</code></pre> <p>See the process scaling documentation for more information on how to manage your app processes.</p>"},{"location":"deployment/application-deployment/#deploying-with-private-git-submodules","title":"Deploying with private Git submodules","text":"<p>Dokku uses Git locally (i.e. not a Docker image) to build its own copy of your app repo, including submodules, as the <code>dokku</code> user. This means that in order to deploy private Git submodules, you need to put your deploy key in <code>/home/dokku/.ssh/</code> and potentially add <code>github.com</code> (or your VCS host key) into <code>/home/dokku/.ssh/known_hosts</code>. You can use the following test to confirm your setup is correct:</p> <pre><code># on the Dokku host\nsu - dokku\nssh-keyscan -t rsa github.com &gt;&gt; ~/.ssh/known_hosts\nssh -T git@github.com\n</code></pre> <p>Warning</p> <p>if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply.</p>"},{"location":"deployment/application-deployment/#deploying-to-subdomains","title":"Deploying to subdomains","text":"<p>If you do not enter a fully qualified domain name when pushing your app, Dokku deploys the app to <code>&lt;remotename&gt;.yourdomain.tld</code> as follows:</p> ShellOutput <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\n# the below example assumes your app server domain or IP is dokku.me. Push in the form of: dokku@{serveripordomain}:{dokkuappname}\ngit remote add dokku dokku@dokku.me:ruby-getting-started\ngit push dokku main\n</code></pre> <pre><code>remote: -----&gt; Application deployed:\nremote:        http://ruby-getting-started.dokku.me\n</code></pre> <p>You can also specify the fully qualified name as follows:</p> ShellOutput <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\ngit remote add dokku dokku@dokku.me:app.dokku.me\ngit push dokku main\n</code></pre> <pre><code>remote: -----&gt; Application deployed:\nremote:        http://app.dokku.me\n</code></pre> <p>This is useful when you want to deploy to the root domain:</p> ShellOutput <pre><code># from your local machine\n# the remote username *must* be dokku or pushes will fail\ngit remote add dokku dokku@dokku.me:dokku.me\ngit push dokku main\n</code></pre> <pre><code>... deployment ...\n\nremote: -----&gt; Application deployed:\nremote:        http://dokku.me\n</code></pre>"},{"location":"deployment/application-deployment/#dokkudocker-container-management-compatibility","title":"Dokku/Docker container management compatibility","text":"<p>Dokku is, at its core, a Docker container manager. Thus, it does not necessarily play well with other out-of-band processes interacting with the Docker daemon.</p> <p>Prior to every deployment, Dokku will execute a cleanup function. As of 0.5.x, the cleanup removes all containers with the <code>dokku</code> label where the status is either <code>dead</code> or <code>exited</code> (previous versions would remove all <code>dead</code> or <code>exited</code> containers). The cleanup function also removes all images with <code>dangling</code> status.</p>"},{"location":"deployment/application-deployment/#adding-deploy-users","title":"Adding deploy users","text":"<p>See the user management documentation for more information on how to manage users with access to your Dokku server.</p>"},{"location":"deployment/application-deployment/#default-vhost","title":"Default vhost","text":"<p>See the domains documentation for more information on how to manage the default site.</p>"},{"location":"deployment/application-deployment/#deploying-non-master-branch","title":"Deploying non-master branch","text":"<p>See the Git documentation for more information on deploying a non-master branch to your application.</p>"},{"location":"deployment/application-deployment/#dockerfile-deployment","title":"Dockerfile deployment","text":"<p>See the Dockerfile documentation for information Dokku's Dockerfile support.</p>"},{"location":"deployment/application-deployment/#image-tagging","title":"Image tagging","text":"<p>See the image tagging documentation for more information on how Docker images can be tagged and deployed for a given application.</p>"},{"location":"deployment/application-deployment/#specifying-a-custom-buildpack","title":"Specifying a custom buildpack","text":"<p>See the herokuish buildpack documentation for more information on how to specify a set of custom buildpacks for your application.</p>"},{"location":"deployment/application-deployment/#removing-a-deployed-app","title":"Removing a deployed app","text":"<p>See the application management documentation for more information on how to remove an application from your Dokku server.</p>"},{"location":"deployment/application-deployment/#renaming-a-deployed-app","title":"Renaming a deployed app","text":"<p>See the application management documentation for more information on how an application can be renamed and the impact of doing so upon the application and associated resources.</p>"},{"location":"deployment/application-deployment/#zero-downtime-deploy","title":"Zero downtime deploy","text":"<p>See the zero-downtime deploy documentation for more information on how Dokku enables zero-downtime deploys.</p>"},{"location":"deployment/application-management/","title":"Application Management","text":"<p>New</p> <p>Introduced in 0.3.1</p> <pre><code>apps:clone &lt;old-app&gt; &lt;new-app&gt;                 # Clones an app\napps:create &lt;app&gt;                              # Create a new app\napps:destroy &lt;app&gt;                             # Permanently destroy an app\napps:exists &lt;app&gt;                              # Checks if an app exists\napps:list                                      # List your apps\napps:lock &lt;app&gt;                                # Locks an app for deployment\napps:locked &lt;app&gt;                              # Checks if an app is locked for deployment\napps:rename &lt;old-app&gt; &lt;new-app&gt;                # Rename an app\napps:report [&lt;app&gt;] [&lt;flag&gt;]                   # Display report about an app\napps:unlock &lt;app&gt;                              # Unlocks an app for deployment\n</code></pre>"},{"location":"deployment/application-management/#usage","title":"Usage","text":""},{"location":"deployment/application-management/#listing-applications","title":"Listing applications","text":"<p>New</p> <p>Introduced in 0.8.1. Use the <code>apps</code> command for older versions.</p> <p>You can easily list all available applications using the <code>apps:list</code> command:</p> ShellOutput <pre><code>dokku apps:list\n</code></pre> <pre><code>=====&gt; My Apps\nnode-js-app\npython-app\n</code></pre> <p>Note that you can easily hide extra output from Dokku commands by using the <code>--quiet</code> flag, which makes it easier to parse on the command line.</p> ShellOutput <pre><code>dokku --quiet apps:list\n</code></pre> <pre><code>node-js-app\npython-app\n</code></pre>"},{"location":"deployment/application-management/#checking-if-an-application-exists","title":"Checking if an application exists","text":"<p>For CI/CD pipelines, it may be useful to see if an application exists before creating a \"review\" application for a specific branch. You can do so via the <code>apps:exists</code> command:</p> ShellOutput <pre><code>dokku apps:exists  node-js-app\n</code></pre> <pre><code>App does not exist\n</code></pre> <p>The <code>apps:exists</code> command will return non-zero if the application does not exist, and zero if it does.</p>"},{"location":"deployment/application-management/#manually-creating-an-application","title":"Manually creating an application","text":"<p>A common pattern for deploying applications to Dokku is to configure an application before deploying it. You can do so via the <code>apps:create</code> command:</p> ShellOutput <pre><code>dokku apps:create node-js-app\n</code></pre> <pre><code>Creating node-js-app... done\n</code></pre> <p>Once created, you can configure the application as normal, and deploy the application whenever ready. This is useful for cases where you may wish to do any of the following kinds of tasks:</p> <ul> <li>Configure domain names and SSL certificates.</li> <li>Create and link datastores.</li> <li>Set environment variables.</li> </ul>"},{"location":"deployment/application-management/#removing-a-deployed-app","title":"Removing a deployed app","text":"<p>In some cases, you may need to destroy an application, whether it is because the application is temporary or because it was misconfigured. In these cases, you can use the <code>apps:destroy</code> command. Performing any destructive actions in Dokku requires confirmation, and this command will ask for the name of the application being deleted before doing so.</p> ShellOutput <pre><code>dokku apps:destroy node-js-app\n</code></pre> <pre><code> !     WARNING: Potentially Destructive Action\n !     This command will destroy node-js-app (including all add-ons).\n !     To proceed, type \"node-js-app\"\n\nDestroying node-js-app (including all add-ons)\n</code></pre> <p>Info</p> <p>node-js-app</p> <p>This will prompt you to verify the application's name before destroying it. You may also use the <code>--force</code> flag to circumvent this verification process:</p> ShellOutput <pre><code>dokku --force apps:destroy node-js-app\n</code></pre> <pre><code>Destroying node-js-app (including all add-ons)\n</code></pre> <p>The <code>--force</code> flag can also be specified on the command vs globally:</p> ShellOutput <pre><code>dokku apps:destroy --force node-js-app\n</code></pre> <pre><code>Destroying node-js-app (including all add-ons)\n</code></pre> <p>Destroying an application will unlink all linked services and destroy any config related to the application. Note that linked services will retain their data for later use (or removal).</p>"},{"location":"deployment/application-management/#renaming-a-deployed-app","title":"Renaming a deployed app","text":"<p>New</p> <p>Introduced in 0.4.7</p> <p>You can rename a deployed app using the <code>apps:rename</code> command. Note that the application must have been deployed at least once, or the rename will not complete successfully:</p> ShellOutput <pre><code>dokku apps:rename node-js-app io-js-app\n</code></pre> <pre><code>Destroying node-js-app (including all add-ons)\n-----&gt; Cleaning up...\n-----&gt; Building io-js-app from herokuish...\n-----&gt; Adding BUILD_ENV to build environment...\n-----&gt; Node.js app detected\n\n-----&gt; Creating runtime environment\n\n...\n\n=====&gt; Application deployed:\n       http://io-js-app.ci.dokku.me\n\nRenaming node-js-app to io-js-app... done\n</code></pre> <p>This will copy all of your app's contents into a new app directory with the name of your choice, delete your old app, then rebuild the new version of the app and deploy it. All of your config variables, including database urls, will be preserved.</p> <p>By default, Dokku will deploy the renamed app, though you can skip the deploy by using the <code>--skip-deploy</code> flag:</p> <pre><code>dokku apps:rename --skip-deploy node-js-app io-js-app\n</code></pre> <p>Remember to also change your git remote on your local machine in order to make <code>git push dokku main</code> work again. For this you can use <code>git remote set-url</code>.</p> <pre><code>git remote set-url dokku dokku@dokku.me:io-js-app\n</code></pre>"},{"location":"deployment/application-management/#cloning-an-existing-app","title":"Cloning an existing app","text":"<p>New</p> <p>Introduced in 0.11.5</p> <p>You can clone an existing app using the <code>apps:clone</code> command.  Note that the application must have been deployed at least once, or cloning will not complete successfully:</p> ShellOutput <pre><code>dokku apps:clone node-js-app io-js-app\n</code></pre> <pre><code>Cloning node-js-app to io-js-app... done\n</code></pre> <p>This will copy all of your app's contents into a new app directory with the name of your choice and then rebuild the new version of the app and deploy it with the following caveats:</p> <ul> <li>All of your environment variables, including database urls, will be preserved.</li> <li>Custom domains are not applied to the new app.</li> <li>SSL certificates will not be copied to the new app.</li> <li>Port mappings with the scheme <code>https</code> and host-port <code>443</code> will be skipped.</li> </ul> <p>Warning</p> <p>If you have exposed specific ports via <code>docker-options</code> plugin, or performed anything that cannot be done against multiple applications, <code>apps:clone</code> may result in errors.</p> <p>By default, Dokku will deploy this new app, though you can skip the deploy by using the <code>--skip-deploy</code> flag:</p> <pre><code>dokku apps:clone --skip-deploy node-js-app io-js-app\n</code></pre> <p>Finally, if the application already exists, you may wish to ignore errors resulting from attempting to clone over it. To do so, you can use the <code>--ignore-existing</code> flag. A warning will be emitted, but the command will return <code>0</code>.</p> <pre><code>dokku apps:clone --ignore-existing node-js-app io-js-app\n</code></pre>"},{"location":"deployment/application-management/#locking-app-deploys","title":"Locking app deploys","text":"<p>New</p> <p>Introduced in 0.11.6</p> <p>If you wish to disable deploying for a period of time, this can be done via deploy locks. Normally, deploy locks exist only for the duration of a deploy so as to avoid deploys from colliding, but a deploy lock can be created by running the <code>apps:lock</code> command.</p> ShellOutput <pre><code>dokku apps:lock node-js-app\n</code></pre> <pre><code>-----&gt; Deploy lock created\n</code></pre>"},{"location":"deployment/application-management/#unlocking-app-deploys","title":"Unlocking app deploys","text":"<p>New</p> <p>Introduced in 0.11.6</p> <p>In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the <code>apps:unlock</code> command.</p> <p>Warning</p> <p>Removing the deploy lock will not stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.</p> ShellOutput <pre><code>dokku apps:unlock node-js-app\n</code></pre> <pre><code> !     A deploy may be in progress.\n !     Removing the app lock will not stop in progress deploys.\n-----&gt; Deploy lock removed.\n</code></pre>"},{"location":"deployment/application-management/#checking-lock-status","title":"Checking lock status","text":"<p>New</p> <p>Introduced in 0.13.0</p> <p>In some cases, you may wish to inspect the state of an app lock. To do so, you can issue an <code>apps:lock</code> command. This will exit non-zero if there is no app lock in place.</p> ShellOutput <pre><code>dokku apps:locked node-js-app\n</code></pre> <pre><code>Deploy lock does not exist\n</code></pre>"},{"location":"deployment/application-management/#displaying-reports-for-an-app","title":"Displaying reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the deployed apps using the <code>apps:report</code> command:</p> ShellOutput <pre><code>dokku apps:report\n</code></pre> <pre><code>=====&gt; node-js-app app information\n       App created at:              1635126111\n       App dir:                     /home/dokku/node-js-app\n       App deploy source:           git\n       App deploy source metadata:  cd7b8afccb202f222e7dc7b427553e71ba5ddafd\n       App locked:                  false\n=====&gt; python-sample app information\n       App created at:              1635126000\n       App dir:                     /home/dokku/python-sample\n       App deploy source:\n       App deploy source metadata:\n       App locked:                  false\n=====&gt; ruby-sample app information\n       App created at:              1635122462\n       App dir:                     /home/dokku/ruby-sample\n       App deploy source:           git\n       App deploy source metadata:  c60921ea2799ca108276414b95ea197f16798d51\n       App locked:                  false\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku apps:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app app information\n       App dir:                     /home/dokku/node-js-app\n       App deploy source:           git\n       App deploy source metadata:  cd7b8afccb202f222e7dc7b427553e71ba5ddafd\n       App locked:                  false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku apps:report node-js-app --app-dir\n</code></pre>"},{"location":"deployment/logs/","title":"Log Management","text":"<pre><code>logs &lt;app&gt; [-h|--help] [-t|--tail] [-n|--num num] [-q|--quiet] [-p|--ps process]  # Display recent log output\nlogs:failed --all|&lt;app&gt;                                                    # Shows the last failed deploy logs\nlogs:report [&lt;app&gt;] [&lt;flag&gt;]                                               # Displays a logs report for one or more apps\nlogs:set [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt;                                    # Set or clear a logs property for an app\nlogs:vector-logs [--num num] [--tail]                                      # Display vector log output\nlogs:vector-start                                                          # Start the vector logging container\nlogs:vector-stop                                                           # Stop the vector logging container\n</code></pre>"},{"location":"deployment/logs/#usage","title":"Usage","text":""},{"location":"deployment/logs/#application-logs","title":"Application logs","text":"<p>You can easily get logs of an app using the <code>logs</code> command:</p> <pre><code>dokku logs node-js-app\n</code></pre> <p>Logs are pulled via integration with the scheduler for the specified application via \"live tailing\". As such, logs from previously running deployments are usually not available. Users that desire to see logs from previous deployments for debugging purposes should persist those logs to external services. Please see Dokku's vector integration for more information on how to persist logs across deployments to ship logs to another service or a third-party platform.</p>"},{"location":"deployment/logs/#behavioral-modifiers","title":"Behavioral modifiers","text":"<p>Dokku also supports certain command-line arguments that augment the <code>log</code> command's behavior.</p> <pre><code>-n, --num NUM        # the number of lines to display\n-p, --ps PS          # only display logs from the given process\n-t, --tail           # continually stream logs\n-q, --quiet          # display raw logs without colors, time and names\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku logs node-js-app -t -p web\n</code></pre> <p>The above command will show logs continually from the web process.</p>"},{"location":"deployment/logs/#failed-deploy-logs","title":"Failed deploy logs","text":"<p>Warning</p> <p>The default docker-local scheduler will \"store\" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.</p> <p>In some cases, it may be useful to retrieve the logs from a previously failed deploy.</p> <p>You can retrieve these logs by using the <code>logs:failed</code> command.</p> <pre><code>dokku logs:failed node-js-app\n</code></pre> <p>You may also fetch all failed app logs by using the <code>--all</code> flag.</p> <pre><code>dokku logs:failed --all\n</code></pre>"},{"location":"deployment/logs/#docker-log-retention","title":"Docker Log Retention","text":"<p>Docker log retention can be specified via the <code>logs:set</code> command by specifying a value for <code>max-size</code>. Log retention is set via injected docker options for all applications, but is also available via the <code>logs-get-property</code> trigger for alternative schedulers.</p> <pre><code>dokku logs:set node-js-app max-size 20m\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku logs:set node-js-app max-size\n</code></pre> <p>Valid values include any integer number followed by a unit of measure (<code>k</code>, <code>m</code>, or <code>g</code>) or the string <code>unlimited</code>. Setting to <code>unlimited</code> will result in Dokku omitting the log option.</p> <p>The <code>max-size</code> property can also be set globally. The global default is <code>10m</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku logs:set --global max-size 20m\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku logs:set --global max-size\n</code></pre>"},{"location":"deployment/logs/#vector-logging-shipping","title":"Vector Logging Shipping","text":"<p>New</p> <p>Introduced in 0.22.6</p> <p>Vector is an open-source, lightweight and ultra-fast tool for building observability pipelines. Dokku integrates with it for shipping container logs for the <code>docker-local</code> scheduler. Users may configure log-shipping on a per-app or global basis, neither of which interfere with the <code>dokku logs</code> commands.</p>"},{"location":"deployment/logs/#starting-the-vector-container","title":"Starting the Vector container","text":"<p>Warning</p> <p>While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected.</p> <p>Vector may be started via the <code>logs:vector-start</code> command.</p> <pre><code>dokku logs:vector-start\n</code></pre> <p>This will start a new container named <code>vector</code> with Dokku's vector config mounted and ready for use. If a running container already exists, this command will do nothing. Additionally, if a container exists but is not running, this command will attempt to start the container.</p> <p>While the default vector image is hardcoded, users may specify an alternative via the <code>--vector-image</code> flag:</p> <pre><code>dokku logs:vector-start --vector-image timberio/vector:latest-debian\n</code></pre> <p>The <code>vector</code> container will be started with the following volume mounts:</p> <ul> <li><code>/var/lib/dokku/data/logs/vector.json:/etc/vector/vector.json</code></li> <li><code>/var/run/docker.sock:/var/run/docker.sock</code></li> <li><code>/var/log/dokku/apps:/var/log/dokku/apps</code></li> </ul> <p>The final volume mount - <code>/var/log/dokku/apps</code> - may be used for users that wish to ship logs to a file on disk that may be later logrotated. This directory is owned by the <code>dokku</code> user and group, with permissions set to <code>0755</code>. At this time, log-rotation is not configured for this directory.</p>"},{"location":"deployment/logs/#stopping-the-vector-container","title":"Stopping the Vector container","text":"<p>Vector may be stopped via the <code>logs:vector-stop</code> command.</p> <pre><code>dokku logs:vector-stop\n</code></pre> <p>The <code>vector</code> container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"deployment/logs/#checking-vectors-logs","title":"Checking Vector's Logs","text":"<p>It may be necessary to check the vector container's logs to ensure that vector is operating as expected. This can be performed with the <code>logs:vector-logs</code> command.</p> <pre><code>dokku logs:vector-logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku logs:vector-logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the vector container, with an initial history of 10 log lines</p>"},{"location":"deployment/logs/#configuring-a-log-sink","title":"Configuring a log sink","text":"<p>Vector uses the concept of log \"sinks\" to send logs to a given endpoint. Log sinks may be configured globally or on a per-app basis by specifying a <code>vector-sink</code> in DSN form with the <code>logs:set</code> command. Specifying a sink value will reload any running vector container.</p> <pre><code># setting the sink value in quotes is encouraged to avoid\n# issues with ampersand encoding in shell commands\ndokku logs:set node-js-app vector-sink \"console://?encoding[codec]=json\"\n</code></pre> <p>A sink may be removed by setting an empty value, which will also reload the running vector container.</p> <pre><code>dokku logs:set node-js-app vector-sink\n</code></pre> <p>Only one sink may be specified on a per-app basis at a given time.</p> <p>Log sinks can also be specified globally by specifying the <code>--global</code> flag to <code>logs:set</code> with no app name specified:</p> <pre><code>dokku logs:set --global vector-sink \"console://?encoding[codec]=json\"\n</code></pre> <p>As with app-specific sink settings, the global value may also be cleared by setting no value.</p> <pre><code>dokku logs:set --global vector-sink\n</code></pre>"},{"location":"deployment/logs/#log-sink-dsn-format","title":"Log Sink DSN Format","text":"<p>The DSN form of a sink is as follows:</p> <pre><code>SINK_TYPE://?SINK_OPTIONS\n</code></pre> <p>Valid values for <code>SINK_TYPE</code> include all log vector log sinks, while <code>SINK_OPTIONS</code> is a query-string form for the sink's options. The following is a short description on how to set various values:</p> <ul> <li><code>bool</code>: form: <code>key=bool</code></li> <li><code>string</code>: form: <code>key=string</code></li> <li><code>int</code>: form: <code>key=int</code></li> <li><code>[string]</code>: form: <code>key[]=string</code></li> <li><code>[int]</code>: form: <code>key[]=int</code></li> <li><code>table</code>: form: <code>option[key]=value</code></li> </ul> <p>For some sinks - such as the <code>http</code> sink - it may be useful to use special characters such as <code>&amp;</code>. These characters must be url escaped as per RFC 3986.</p> <pre><code># the following command will set the `http` sink with a uri config value\n# for a uri config value: https://loggerservice.com:1234/?token=abc1234&amp;type=vector\n# the url quoted version: https%3A//loggerservice.com%3A1234/%3Ftoken%3Dabc1234%26type%3Dvector\ndokku logs:set test vector-sink \"http://?uri=https%3A//loggerservice.com%3A1234/%3Ftoken%3Dabc1234%26type%3Dvector\"\n</code></pre> <p>Please read the sink documentation for your sink of choice to configure the sink as desired.</p>"},{"location":"deployment/remote-commands/","title":"Remote Commands","text":"<p>Dokku commands can be run over SSH. Anywhere you would run <code>dokku &lt;command&gt;</code>, just run <code>ssh -t dokku@dokku.me &lt;command&gt;</code> The <code>-t</code> is used to request a pty. It is highly recommended to do so. To avoid the need to type the <code>-t</code> option each time, create/modify a section in the <code>.ssh/config</code> on the client side, as follows:</p> <pre><code>Host dokku.me\n    RequestTTY yes\n</code></pre>"},{"location":"deployment/remote-commands/#behavioral-modifiers","title":"Behavioral modifiers","text":"<p>Dokku also supports certain command line arguments that augment its behavior. If using these over SSH, you must use the form <code>ssh -t dokku@dokku.me -- &lt;command&gt;</code> to avoid SSH interpreting Dokku arguments for itself.</p> <pre><code>--quiet                suppress output headers\n--trace                enable DOKKU_TRACE for current execution only\n--force                force flag. currently used in apps:destroy and other \":destroy\" commands\n</code></pre>"},{"location":"deployment/remote-commands/#official-client","title":"Official Client","text":"<p>You may optionally use the official client when connecting to the Dokku server.</p> <p>Of all methods, this is the most official method of interacting with your Dokku installation. It is a bash script that interacts with a remote Dokku installation via <code>ssh</code>. It is available in <code>contrib/dokku_client.sh</code> in the root of the Dokku repository.</p> <p>It can be installed either via the Homebrew package manager (macOS only), or manually.</p>"},{"location":"deployment/remote-commands/#installation-via-homebrew","title":"Installation via Homebrew","text":"<p>To install, simply run the following command:</p> <pre><code>brew install dokku/repo/dokku\n</code></pre>"},{"location":"deployment/remote-commands/#manual-installation","title":"Manual installation","text":"<p>To install manually, simply clone the Dokku repository down and add the <code>dokku</code> alias pointing at the script:</p> <pre><code>git clone git@github.com:dokku/dokku.git ~/.dokku\n\n# optional: make sure that the dokku_client.sh version matches your Dokku version\ncd ~/.dokku\ngit checkout &lt;tag/branch&gt;\n\n# add the following to either your\n# .bashrc, .bash_profile, or .profile file\nalias dokku='$HOME/.dokku/contrib/dokku_client.sh'\n</code></pre> <p>Alternatively, if using another shell such as zsh, create an alias command which invokes the script using bash:</p> <pre><code># zsh: add the following to either .zshenv or .zshrc\nalias dokku='bash $HOME/.dokku/contrib/dokku_client.sh'\n\n# fish: add the following to ~/.config/fish/config.fish\nalias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh'\n\n# csh: add the following to .cshrc\nalias dokku 'bash $HOME/.dokku/contrib/dokku_client.sh'\n</code></pre>"},{"location":"deployment/remote-commands/#usage","title":"Usage","text":"<p>All commands have the application name automatically set via the <code>--app</code> flag on the remote server, and thus the app name does not need to be specified manually for core plugins.</p> <p>The client supports several environment variables:</p> <ul> <li><code>DOKKU_HOST</code> (default: <code>dokku</code> git remote): Used to interact with a specific remote server. Can be overridden via the <code>--remote</code> flag.</li> <li><code>DOKKU_PORT</code> (default: <code>22</code>): Used to specify a port to connect to the Dokku server on.</li> </ul> <p>It also supports several flags (all flags unspecified here are passed as is to the server):</p> <ul> <li><code>--app</code>: Override the remote app in use.</li> <li><code>--trace</code>: Enable trace mode.</li> <li><code>--remote</code>: Override the remote server.</li> <li><code>--global</code>: Unsets the \"app\" value. May not be supported for the specified command.</li> </ul> <p>In addition, the following commands have special local side-effects:</p> <ul> <li><code>apps:create</code>:<ul> <li>If no local <code>--app</code> flag is specified or detected from a <code>dokku</code> git remote, a random name is generated and used for the app.</li> <li>The <code>dokku</code> git remote is set if not already set.</li> </ul> </li> <li><code>apps:destroy</code>:<ul> <li>Removes the local <code>dokku</code> git remote if set.</li> </ul> </li> </ul>"},{"location":"deployment/remote-commands/#specifying-a-remote","title":"Specifying a remote","text":"<p>While many users will only ever push to a single dokku remote from a given repository, it may be useful to point the same repository at multiple remotes, especially in the case of pre-production environments. This can be done via the <code>remote</code> commands. These commands are only available within the official remote client, and are not server-side commands.</p> <p>To see your currently configured remote, run <code>dokku remote</code>. This will respect the <code>--remote</code> flag.</p> <p>To list all available remotes, run <code>dokku remote:list</code>. This is equivalent to running <code>git remote</code>.</p> <p>To add a remote, run <code>dokku remote:add $REMOTE_NAME dokku@dokku.me:$APP_NAME</code>, replacing <code>$REMOTE_NAME</code> with your desired remote name, the <code>$APP_NAME</code> with your desired app name and the host <code>dokku.me</code> with your Dokku host. This is equivalent to running <code>git remote add $REMOTE_NAME dokku@dokku.me:$APP_NAME</code>.</p> <p>To remove a remote, run <code>dokku remote:remove $REMOTE_NAME</code>. This is equivalent to running <code>git remote remove $REMOTE_NAME</code>.</p> <p>By default, the remote in use is <code>dokku</code>. To change the remote the client uses by default, run <code>dokku remote:set $REMOTE_NAME</code>, where <code>$REMOTE_NAME</code> is the name of your desired remote. This will not check the value specified, so that remote must be available or errors will occur when running normal client commands. Note that specifying <code>--remote</code> when running dokku commands will override this configuration value.</p> <p>To clear the configured remote, run <code>dokku remote:unset</code>. The client will unset the configured remote, and will default back to <code>dokku</code>, or the value of <code>--remote</code> if specified.</p>"},{"location":"deployment/remote-commands/#unofficial-clients","title":"Unofficial Clients","text":"<p>Please refer to the community clients list for more details.</p>"},{"location":"deployment/user-management/","title":"User Management","text":"<p>New</p> <p>Introduced in 0.7.0</p> <pre><code>ssh-keys:add &lt;name&gt; [/path/to/key]                 # Add a new public key by pipe or path\nssh-keys:list [--format text|json] [&lt;name&gt;]        # List of all authorized Dokku public ssh keys\nssh-keys:remove [--fingerprint fingerprint|&lt;name&gt;] # Remove SSH public key by name\n</code></pre> <p>When pushing to Dokku, SSH key-based authorization is the preferred authentication method, for ease of use and increased security.</p> <p>Users in Dokku are managed via the <code>~/dokku/.ssh/authorized_keys</code> file. It is highly recommended that you follow the steps below to manage users on a Dokku server.</p> <p>Info</p> <p>Users of older versions of Dokku may use the <code>sshcommand</code> binary to manage keys instead of the <code>ssh-keys</code> plugin. Please refer to the Dokku documentation for your version for more details.</p>"},{"location":"deployment/user-management/#usage","title":"Usage","text":""},{"location":"deployment/user-management/#listing-ssh-keys","title":"Listing SSH keys","text":"<p>You can use the <code>ssh-keys:list</code> command to show all configured SSH keys.</p> ShellOutput <pre><code>dokku ssh-keys:list\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc NAME=\"admin\" SSHCOMMAND_ALLOWED_KEYS=\"no-agent-forwarding,no-user-rc,no-X11-forwarding,no-port-forwarding\"\n</code></pre> <p>The output contains the following information:</p> <ul> <li>SSH Key Fingerprint.</li> <li>The <code>KEY_NAME</code>.</li> <li>A comma separated list of SSH options under the <code>SSHCOMMAND_ALLOWED_KEYS</code> name.</li> </ul> <p>New</p> <p>Introduced in 0.20.2</p> <p>The keys for a specific user may be listed by specifying a second argument to the <code>ssh-keys:list</code> command:</p> <pre><code>dokku ssh-keys:list admin\n</code></pre> <p>New</p> <p>Introduced in 0.22.3</p> <p>The output format may be specified via the <code>--format</code> flag. Supported values include <code>json</code> and <code>text</code>.</p> <pre><code>dokku ssh-keys:list --format json\n</code></pre> <p>This can additionally be used to filter to keys for a particular user:</p> <pre><code>dokku ssh-keys:list --format json admin\n</code></pre>"},{"location":"deployment/user-management/#adding-ssh-keys","title":"Adding SSH keys","text":"<p>You can add your public key to Dokku with the <code>ssh-keys:add</code> command. The path specified must contain your desired public ssh key contents and must exist on the server. Any special characters - such as <code>~</code> - are interpreted under the <code>dokku</code> user context. The output will be the fingerprint of the SSH key:</p> ShellOutput <pre><code>dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc\n</code></pre> <p><code>KEY_NAME</code> is the name you want to use to refer to this particular key. Including the word <code>admin</code> in the name will grant the user privileges to add additional keys remotely.</p> <p>Info</p> <p><code>KEY_NAME</code> is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The SSH (Git) user is always <code>dokku</code>, as this is the system user that the <code>dokku</code> binary uses to perform all its actions.</p> <p>Alternatively, you may pipe the contents of your ssh key via <code>cat</code> or <code>echo</code> into the <code>ssh-keys:add</code> command instead of specifying a path to the ssh key:</p> ShellOutputShellOutput <pre><code>echo \"$CONTENTS_OF_YOUR_PUBLIC_SSH_KEY_HERE\" | dokku ssh-keys:add KEY_NAME\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc\n</code></pre> <pre><code>cat path/to/id_rsa.pub | dokku ssh-keys:add KEY_NAME\n</code></pre> <pre><code>SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc\n</code></pre> <p>Admin users and root can add keys remotely by specifying the <code>dokku</code> bin on their <code>ssh</code> command:</p> <pre><code>cat ~/.ssh/id_rsa.pub | ssh root@dokku.me dokku ssh-keys:add KEY_NAME\n</code></pre> <p>If you are using the Vagrant installation, you can also use the <code>make vagrant-acl-add</code> target to add your public key to Dokku (it will use your host username as the <code>USER</code>):</p> <pre><code>cat ~/.ssh/id_rsa.pub | make vagrant-acl-add\n</code></pre>"},{"location":"deployment/user-management/#removing-ssh-keys","title":"Removing SSH keys","text":"<p>As key names are unique, they can be used to remove a public SSH key.</p> <pre><code>dokku ssh-keys:remove KEY_NAME\n</code></pre> <p>An SSH Key can also be removed by fingerprint.</p> <pre><code>dokku ssh-keys:remove --fingerprint FINGERPRINT\n</code></pre>"},{"location":"deployment/user-management/#scoping-commands-to-specific-users","title":"Scoping commands to specific users","text":"<p>Support for scoping commands to specific users can be added through plugins that take advantage of the user-auth plugin trigger to handle command authorization. See also the list of community-provided plugins.</p>"},{"location":"deployment/user-management/#granting-other-unix-user-accounts-dokku-access","title":"Granting other Unix user accounts Dokku access","text":"<p>Any Unix user account which belongs to the <code>sudo</code> Unix group can run Dokku.  However, you may want to give them Dokku access but not full sudo privileges.</p> <p>To allow other Unix user accounts to be able to run Dokku commands, without giving them full sudo access, modify your sudoers configuration.</p> <p>Use <code>visudo /etc/sudoers.d/dokku-users</code>, or <code>visudo /etc/sudoers</code> to add the following line:</p> <pre><code>%dokku ALL=(ALL:ALL) NOPASSWD:SETENV: /usr/bin/dokku\n</code></pre>"},{"location":"deployment/zero-downtime-deploys/","title":"Zero Downtime Deploy Checks","text":"<p>New</p> <p>Introduced in 0.5.0</p> <pre><code>checks:disable &lt;app&gt; [process-type(s)]    Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments***\nchecks:enable &lt;app&gt; [process-type(s)]     Enable zero-downtime deployment for all processes (or comma-separated process-type list)\nchecks:report [&lt;app&gt;] [&lt;flag&gt;]            Displays a checks report for one or more apps\nchecks:run &lt;app&gt; [process-type(s)]        Runs zero-downtime checks for all processes (or comma-separated process-type list)\nchecks:set [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt; Set or clear a logs property for an app\nchecks:skip &lt;app&gt; [process-type(s)]       Skip zero-downtime checks for all processes (or comma-separated process-type list)\n</code></pre> <p>By default, Dokku will wait <code>10</code> seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by an application, traffic will be switched to point to your new containers. Dokku will also wait a further <code>60</code> seconds after the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application.</p> <p>You may both create user-defined checks for web processes using the <code>healthchecks</code> key in the <code>app.json</code> file, as well as customize any and all parts of this experience using the checks plugin.</p> <p>Info</p> <p>Web checks are performed via <code>curl</code> on Dokku host. Some application code - such as the Django framework - checks for specific hostnames or header values, these checks will fail. To avoid this:</p> <ul> <li>Remove such checks from your code: Modify your application to remove the hostname check completely.</li> <li>Allow checks from all hostnames: Modify your application to accept a dynamically provided hostname.</li> <li>Specify the domain within the check: See below for further documentation.</li> </ul>"},{"location":"deployment/zero-downtime-deploys/#configuring-checks-settings","title":"Configuring checks settings","text":""},{"location":"deployment/zero-downtime-deploys/#wait-to-retire","title":"wait-to-retire","text":"<p>After a successful deploy, the grace period given to old containers before they are stopped/terminated is determined by the value of <code>wait-to-retire</code>. This is useful for ensuring completion of long-running HTTP connections.</p> <pre><code>dokku checks:set node-js-app wait-to-retire 30\n</code></pre> <p>Defaults to <code>60</code>.</p>"},{"location":"deployment/zero-downtime-deploys/#configuring-check-settings-using-the-config-plugin","title":"Configuring check settings using the <code>config</code> plugin","text":"<p>There are certain settings that can be configured via environment variables:</p> <ul> <li><code>DOKKU_DEFAULT_CHECKS_WAIT</code>: (default: <code>10</code>) If no user-defined checks are specified - or if the process being checked is not a <code>web</code> process - this is the period of time Dokku will wait before checking that a container is still running.</li> <li><code>DOKKU_DOCKER_STOP_TIMEOUT</code>: (default: <code>10</code>) Configurable grace period given to the <code>docker stop</code> command. If a container has not stopped by this time, a <code>kill -9</code> signal or equivalent is sent in order to force-terminate the container. Both the <code>ps:stop</code> and <code>apps:destroy</code> commands also respect this value. If not specified, the Docker defaults for the <code>docker stop</code> command will be used.</li> </ul> <p>The following settings may also be specified in the <code>app.json</code> file, though are available as environment variables in order to ease application reuse.</p> <ul> <li><code>DOKKU_CHECKS_WAIT</code>: (default: <code>5</code>) Wait this many seconds for the container to start before running checks.</li> <li><code>DOKKU_CHECKS_TIMEOUT</code>: (default: <code>30</code>) Wait this many seconds for each response before marking it as a failure.</li> <li><code>DOKKU_CHECKS_ATTEMPTS</code>: (default: <code>5</code>) Number of retries for to run for a specific check before marking it as a failure</li> </ul>"},{"location":"deployment/zero-downtime-deploys/#skipping-and-disabling-checks","title":"Skipping and Disabling Checks","text":"<p>Info</p> <p>Note that <code>checks:disable</code> will now (as of 0.6.0) cause downtime for that process-type during deployments. Previously, it acted as <code>checks:skip</code> currently does.</p> <p>You can choose to skip checks completely on a per-application/per-process basis. Skipping checks will avoid the default 10 second waiting period entirely, as well as any other user-defined checks.</p> ShellOutput <pre><code># process type specification is optional\ndokku checks:skip node-js-app worker,web\n</code></pre> <pre><code>-----&gt; Skipping zero downtime for app's (node-js-app) proctypes (worker,web)\n-----&gt; Unsetting node-js-app\n-----&gt; Unsetting DOKKU_CHECKS_DISABLED\n-----&gt; Setting config vars\n       DOKKU_CHECKS_SKIPPED: worker,web\n</code></pre> <p>Zero downtime checks can also be disabled completely. This will stop old containers before new ones start, which may result in broken connections and downtime if your application fails to boot properly.</p> ShellOutput <pre><code>dokku checks:disable node-js-app worker\n</code></pre> <pre><code>-----&gt; Disabling zero downtime for app's (node-js-app) proctypes (worker)\n-----&gt; Setting config vars\n       DOKKU_CHECKS_DISABLED: worker\n-----&gt; Setting config vars\n       DOKKU_CHECKS_SKIPPED: web\n</code></pre>"},{"location":"deployment/zero-downtime-deploys/#displaying-checks-reports-for-an-app","title":"Displaying checks reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's checks status using the <code>checks:report</code> command:</p> ShellOutput <pre><code>dokku checks:report\n</code></pre> <pre><code>=====&gt; node-js-app checks information\n       Checks disabled list: none\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n=====&gt; python-app checks information\n       Checks disabled list: none\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n=====&gt; ruby-app checks information\n       Checks disabled list: _all_\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku checks:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app checks information\n       Checks disabled list: none\n       Checks skipped list: none\n       Checks computed wait to retire: 60\n       Checks global wait to retire: 60\n       Checks wait to retire:\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku checks:report node-js-app --checks-disabled-list\n</code></pre>"},{"location":"deployment/zero-downtime-deploys/#customizing-checks","title":"Customizing checks","text":"<p>New</p> <p>Introduced in 0.31.0</p> <p>If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use Dokku's <code>checks</code> functionality to more precisely check whether an application can serve traffic or not.</p> <p>Healthchecks are run against all process from your application's <code>Procfile</code>. When no healthcheck is defined, Dokku will fallback to a process uptime check.</p> <p>One or more healthchecks can be defined in the <code>app.json</code> file - see the deployment task documentation for more information on how this is extracted - under the <code>healthchecks.web</code> path:</p> <pre><code>{\n  \"healthchecks\": {\n    \"web\": [\n        {\n            \"type\":        \"startup\",\n            \"name\":        \"web check\",\n            \"description\": \"Checking if the app responds to the /health/ready endpoint\",\n            \"path\":        \"/health/ready\",\n            \"attempts\": 3\n        }\n    ]\n  }\n}\n</code></pre> <p>A healthcheck entry takes the following properties:</p> <ul> <li><code>attempts</code>: (default: <code>3</code>) Number of retry attempts to perform on failure.</li> <li><code>command</code>: (default <code>''</code> - empty string) Command to execute within container.</li> <li><code>content</code>: (default: <code>''</code> - empty string) Content to search in http path check output.</li> <li><code>initialDelay</code>: (default: 0, unit: seconds) Number of seconds to wait after a container has started before triggering the healthcheck.</li> <li><code>name</code>: (default: autogenerated) The name of the healthcheck. If unspecified, it will be autogenerated from the rest of the healthcheck information.</li> <li><code>path</code>: (default: <code>/</code> - for http checks): An http path to check.</li> <li><code>timeout</code>: (default: <code>5</code> seconds): Number of seconds to wait before timing out a healthcheck.</li> <li><code>type</code>: (default: <code>\"\"</code> - none): Type of the healthcheck. Options: liveness, readiness, startup.</li> <li><code>uptime</code>: (default: <code>\"\"</code> - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries.</li> <li><code>wait</code>: (default: <code>5</code> seconds): Number of seconds to wait between healthcheck attempts.</li> </ul> <p>Warning</p> <p>Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported.</p> <p>See the docker-container-healthchecker documentation for more details on how healthchecks are interpreted.</p>"},{"location":"deployment/zero-downtime-deploys/#manually-invoking-checks","title":"Manually invoking checks","text":"<p>Checks can also be manually invoked via the <code>checks:run</code> command. This can be used to check the status of an application via cron to provide integration with external healthchecking software.</p> <p>Checks are run against a specific application:</p> ShellOutput <pre><code>dokku checks:run APP\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\n-----&gt; Running checks for app (APP.web.1)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n-----&gt; Running checks for app (APP.web.2)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n-----&gt; Running checks for app (APP.worker.1)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n</code></pre> <p>Checks can be scoped to a particular process type:</p> ShellOutput <pre><code>dokku checks:run node-js-app worker\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\n-----&gt; Running checks for app (APP.worker.1)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n</code></pre> <p>An app process ID may also be specified:</p> ShellOutput <pre><code>dokku checks:run node-js-app web.2\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\n-----&gt; Running checks for app (APP.web.2)\n       For more efficient zero downtime deployments, create a file CHECKS.\n       See https://dokku.com/docs/deployment/zero-downtime-deploys/ for examples\n       CHECKS file not found in container: Running simple container check...\n-----&gt; Waiting for 10 seconds ...\n-----&gt; Default container check successful!\n</code></pre> <p>Non-existent process types will result in an error:</p> ShellOutput <pre><code>dokku checks:run node-js-app non-existent\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\nInvalid process type specified (APP.non-existent)\n</code></pre> <p>Non-existent process IDs will also result in an error</p> ShellOutput <pre><code>dokku checks:run node-js-app web.3\n</code></pre> <pre><code>-----&gt; Running pre-flight checks\nInvalid container id specified (APP.web.3)\n</code></pre>"},{"location":"deployment/builders/builder-management/","title":"Builder Management","text":"<p>New</p> <p>Introduced in 0.24.0</p> <pre><code>builder:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder report for one or more apps\nbuilder:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder property for an app\n</code></pre> <p>Builders are a way of customizing how an app is built from a source, allowing users flexibility in how artifacts are created for later scheduling.</p>"},{"location":"deployment/builders/builder-management/#usage","title":"Usage","text":""},{"location":"deployment/builders/builder-management/#builder-selection","title":"Builder selection","text":"<p>Dokku supports the following built-in builders:</p> <ul> <li><code>builder-dockerfile</code>: Builds apps using a <code>Dockerfile</code> via <code>docker build</code>. See the dockerfile builder documentation for more information on how this builder functions.</li> <li><code>builder-herokuish</code>: Builds apps with Heroku's v2a Buildpack specification via <code>gliderlabs/herokuish</code>. See the herokuish builder documentation for more information on how this builder functions.</li> <li><code>builder-lambda</code>: Builds AWS Lambda functions in an environment simulating AWS Lambda runtimes via lambda-builder. See the lambda builder documentation for more information on how this builder functions.</li> <li><code>builder-null</code>: Does nothing during the build phase. See the null builder documentation for more information on how this builder functions.</li> <li><code>builder-pack</code>: Builds apps with Cloud Native Buildpacks via the <code>pack-cli</code>  tool. See the cloud native buildpacks builder documentation for more information on how this builder functions.</li> </ul> <p>Builders run a detection script against a source code repository, and the first detected builder will be used to build the app artifact. The exception to this is when a <code>Dockerfile</code> is detected and the app is also able to use either <code>herokuish</code> or <code>pack-cli</code> for building, in which case one of the latter will be chosen.</p>"},{"location":"deployment/builders/builder-management/#overriding-the-auto-selected-builder","title":"Overriding the auto-selected builder","text":"<p>If desired, the builder can be specified via the <code>builder:set</code> command by speifying a value for <code>selected</code>. The selected builder will always be used.</p> <pre><code>dokku builder:set node-js-app selected dockerfile\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder:set node-js-app selected\n</code></pre> <p>The <code>selected</code> property can also be set globally. The global default is an empty string, and auto-detection will be performed when no value is set per-app or globally.</p> <pre><code>dokku builder:set --global selected herokuish\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder:set --global selected\n</code></pre>"},{"location":"deployment/builders/builder-management/#changing-the-build-directory","title":"Changing the build directory","text":"<p>Warning</p> <p>Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the <code>git.keep-git-dir</code> property.</p> <p>When deploying a monorepo, it may be desirable to specify the specific build directory to use for a given app. This can be done via the <code>builder:set</code> command. If a value is specified and that directory does not exist within the repository, the build will fail.</p> <pre><code>dokku builder:set node-js-app build-dir app2\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder:set node-js-app build-dir\n</code></pre> <p>The <code>build-dir</code> property can also be set globally. The global default is empty string, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder:set --global build-dir app2\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder:set --global build-dir\n</code></pre>"},{"location":"deployment/builders/builder-management/#displaying-builder-reports-for-an-app","title":"Displaying builder reports for an app","text":"<p>You can get a report about the app's builder status using the <code>builder:report</code> command:</p> ShellOutput <pre><code>dokku builder:report\n</code></pre> <pre><code>=====&gt; node-js-app builder information\n       Builder build dir:          custom\n       Builder computed build dir: custom\n       Builder computed selected:  herokuish\n       Builder global build dir:\n       Builder global selected: herokuish\n       Builder selected: herokuish\n=====&gt; python-sample builder information\n       Builder build dir:\n       Builder computed build dir:\n       Builder computed selected: dockerfile\n       Builder global build dir:\n       Builder global selected: herokuish\n       Builder selected: dockerfile\n=====&gt; ruby-sample builder information\n       Builder build dir:\n       Builder computed build dir:\n       Builder computed selected: herokuish\n       Builder global build dir:\n       Builder global selected: herokuish\n       Builder selected:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder information\n       Builder selected: herokuish\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku builder:report node-js-app --builder-selected\n</code></pre>"},{"location":"deployment/builders/builder-management/#custom-builders","title":"Custom builders","text":"<p>To create a custom builder, the following triggers must be implemented:</p> <ul> <li><code>builder-build</code>:<ul> <li>arguments: <code>BUILDER_TYPE</code> <code>APP</code> <code>SOURCECODE_WORK_DIR</code></li> <li>description: Creates a docker image named with the output of <code>common#get_app_image_name $APP</code>.</li> </ul> </li> <li><code>builder-detect</code>:<ul> <li>arguments: <code>APP</code> <code>SOURCECODE_WORK_DIR</code></li> <li>description: Outputs the name of the builder (without the <code>builder-</code> prefix) to use to build the app.</li> </ul> </li> <li><code>builder-release</code>:<ul> <li>arguments: <code>BUILDER_TYPE</code> <code>APP</code> <code>IMAGE_AG</code></li> <li>description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately.</li> </ul> </li> </ul> <p>Custom plugins names must have the prefix <code>builder-</code> or builder overriding via <code>builder:set</code> may not function as expected.</p> <p>Builders can use any tools available on the system to build the docker image, and may even be used to schedule building off-server. The only current requirement is that the image must exist on the server at the end of the <code>builder-build</code> command, though this requirement may be relaxed in a future release.</p> <p>For a simple example of how to implement this trigger, see <code>builder-pack</code>, which utilizes a cli tool - <code>pack-cli</code> - to generate an OCI image that is compatible with Docker and can be scheduled by the official scheduling plugins.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/","title":"Cloud Native Buildpacks","text":"<p>New</p> <p>Introduced in 0.22.0</p> <pre><code>builder-pack:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-pack report for one or more apps\nbuilder-pack:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-pack property for an app\n</code></pre> <pre><code>buildpacks:set-property [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt;  # Set or clear a buildpacks property for an app\n</code></pre> <p>Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the herokuish buildpacks documentation for more information on how to clear buildpack build cache for an application.</p> <p>Warning</p> <p>This functionality uses the <code>pack</code> cli from the Cloud Native Buildpacks project to build apps. As the integration is experimental in Dokku, it is likely to change over time.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/#usage","title":"Usage","text":""},{"location":"deployment/builders/cloud-native-buildpacks/#requirements","title":"Requirements","text":"<p>The <code>pack</code> cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on this page.</p> <p>Builds will proceed with the <code>pack</code> cli for the app from then on.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/#caveats","title":"Caveats","text":"<p>As this functionality is highly experimental, there are a number of caveats. Please note that not all issuesare listed below.</p> <ul> <li>Specifying specific buildpacks is not currently possible.<ul> <li>A future release will add support for specifying buildpacks via the <code>buildpacks</code> plugin.</li> </ul> </li> <li>There is currently no way to specify extra arguments for <code>pack</code> cli invocations.<ul> <li>A future release will add support for injecting extra arguments during the build process.</li> </ul> </li> <li>The default process type is <code>web</code>.</li> <li>Build cache is stored in Docker volumes instead of on disk. As such, <code>repo:purge-cache</code> currently has no effect.<ul> <li>A future version will add integration with the <code>repo</code> plugin.</li> </ul> </li> <li><code>pack</code> is not currently included with Dokku, nor is it added as a package dependency.<ul> <li>A future version will include it as a package dependency.</li> </ul> </li> </ul>"},{"location":"deployment/builders/cloud-native-buildpacks/#detection","title":"Detection","text":"<p>This builder will be auto-detected in either the following cases:</p> <ul> <li> <p>The <code>DOKKU_CNB_EXPERIMENTAL</code> app environment variable is set to <code>1</code>.</p> <pre><code>dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1\n</code></pre> </li> <li> <p>A <code>project.toml</code> file exists in the root of the app repository.</p> <ul> <li>This file is consumed by <code>pack-cli</code> and used to describe how the app is built.</li> </ul> </li> </ul> <p>The builder can also be specified via the <code>builder:set</code> command:</p> <pre><code>dokku builder:set node-js-app selected pack\n</code></pre> <p>Info</p> <p>Dokku will only select the <code>dockerfile</code> builder if both the <code>herokuish</code> and <code>pack</code> builders are not detected and a Dockerfile exists. See the dockerfile builder documentation for more information on how that builder functions.</p>"},{"location":"deployment/builders/cloud-native-buildpacks/#changing-the-projecttoml-location","title":"Changing the <code>project.toml</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>project.toml</code> file to use for a given app. This can be done via the <code>builder-pack:set</code> command. If a value other than <code>project.toml</code> is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no <code>project.toml</code>.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>project.toml</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>project.toml</code> extracted directly from the source code. Both cases will respect the configured <code>projecttoml-path</code> property value.</p> <pre><code>dokku builder-pack:set node-js-app projecttoml-path .dokku/project.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-pack:set node-js-app projecttoml-path\n</code></pre> <p>The <code>projecttoml-path</code> property can also be set globally. The global default is <code>project.toml</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-pack:set --global projecttoml-path project2.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-pack:set --global projecttoml-path\n</code></pre>"},{"location":"deployment/builders/cloud-native-buildpacks/#displaying-builder-pack-reports-for-an-app","title":"Displaying builder-pack reports for an app","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>You can get a report about the app's storage status using the <code>builder-pack:report</code> command:</p> ShellOutput <pre><code>dokku builder-pack:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-pack information\n       Builder pack computed projecttoml path: project2.toml\n       Builder pack global projecttoml path:   project.toml\n       Builder pack projecttoml path:          project2.toml\n=====&gt; python-sample builder-pack information\n       Builder pack computed projecttoml path: project.toml\n       Builder pack global projecttoml path:   project.toml\n       Builder pack projecttoml path:\n=====&gt; ruby-sample builder-pack information\n       Builder pack computed projecttoml path: project.toml\n       Builder pack global projecttoml path:   project.json\n       Builder pack projecttoml path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-pack:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-pack information\n       Builder pack computed projecttoml path: project2.toml\n       Builder pack global projecttoml path:   project.toml\n       Builder pack projecttoml path:          project2.toml\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-pack:report node-js-app --builder-pack-projecttoml-path\n</code></pre> <pre><code>project2.toml\n</code></pre>"},{"location":"deployment/builders/cloud-native-buildpacks/#customizing-the-buildpack-stack-builder","title":"Customizing the Buildpack stack builder","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>The default stack builder in use by CNB buildpacks in Dokku is based on <code>heroku/builder:22</code>. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the <code>buildpacks:set-property</code> command.</p> <pre><code>dokku buildpacks:set-property node-js-app stack paketobuildpacks/build:base-cnb\n</code></pre> <p>The specified stack builder can also be unset by omitting the name of the stack builder when calling <code>buildpacks:set-property</code>.</p> <pre><code>dokku buildpacks:set-property node-js-app stack\n</code></pre> <p>A change in the stack builder value will execute the <code>post-stack-set</code> trigger.</p> <p>Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set <code>DOKKU_CNB_BUILDER</code> environment variable (<code>heroku/builder:22</code> by default).</p> <pre><code># set globally\ndokku buildpacks:set-property --global stack paketobuildpacks/build:base-cnb\n\n# unset globally\ndokku buildpacks:set-property --global stack\n</code></pre>"},{"location":"deployment/builders/cloud-native-buildpacks/#specifying-commands-via-procfile","title":"Specifying commands via Procfile","text":"<p>See the Procfile documentation for more information on how to specify different processes for your app.</p>"},{"location":"deployment/builders/dockerfiles/","title":"Dockerfile Deployment","text":"<p>New</p> <p>Introduced in 0.3.15</p> <pre><code>builder-dockerfile:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-dockerfile report for one or more apps\nbuilder-dockerfile:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-dockerfile property for an app\n</code></pre> <p>While Dokku normally defaults to using Heroku buildpacks for deployment, you can also use Docker's native <code>Dockerfile</code> system to define a container.</p> <p>Info</p> <p>Dockerfile support is considered a power user feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.</p>"},{"location":"deployment/builders/dockerfiles/#usage","title":"Usage","text":""},{"location":"deployment/builders/dockerfiles/#detection","title":"Detection","text":"<p>This builder will be auto-detected in the following case:</p> <ul> <li>A <code>Dockerfile</code> exists in the root of the app repository.</li> </ul> <p>Dokku will only select the <code>dockerfile</code> builder if both the <code>herokuish</code> and <code>pack</code> builders are not detected and a Dockerfile exists. For more information on how those are detected, see the following links:</p> <ul> <li>Cloud Native Buildpacks documentation</li> <li>Herokuish documentation</li> </ul>"},{"location":"deployment/builders/dockerfiles/#switching-from-buildpack-deployments","title":"Switching from buildpack deployments","text":"<p>If an application was previously deployed via buildpacks and ports were customized, the following commands should be run prior to a deploy to ensure the Dockerfile ports are respected:</p> <pre><code>dokku ports:clear node-js-app\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#changing-the-dockerfile-location","title":"Changing the <code>Dockerfile</code> location","text":"<p>Info</p> <p>The previous method to perform this - via <code>docker-options:add</code> - should be removed in favor of the <code>builder-dockerfile:set</code> command outlined here.</p> <p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>Dockerfile</code> file to use for a given app. This can be done via the <code>builder-dockerfile:set</code> command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.</p> <p>For git push, <code>git:from-archive</code>, and <code>git:sync</code> workflows, the <code>Dockerfile</code> is extracted directly from the source code, respecting the configured <code>dockerfile-path</code> property value.</p> <pre><code>dokku builder-dockerfile:set node-js-app dockerfile-path Dockerfile2\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-dockerfile:set node-js-app dockerfile-path\n</code></pre> <p>The <code>dockerfile-path</code> property can also be set globally. The global default is <code>Dockerfile</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-dockerfile:set --global dockerfile-path Dockerfile2\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-dockerfile:set --global dockerfile-path\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#displaying-builder-dockerfile-reports-for-an-app","title":"Displaying builder-dockerfile reports for an app","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>You can get a report about the app's storage status using the <code>builder-dockerfile:report</code> command:</p> ShellOutput <pre><code>dokku builder-dockerfile:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile2\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:          Dockerfile2\n=====&gt; python-sample builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:\n=====&gt; ruby-sample builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-dockerfile:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-dockerfile information\n       Builder dockerfile computed dockerfile path: Dockerfile2\n       Builder dockerfile global dockerfile path:   Dockerfile\n       Builder dockerfile dockerfile path:          Dockerfile2\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-dockerfile:report node-js-app --builder-dockerfile-dockerfile-path\n</code></pre> <pre><code>Dockerfile2\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#build-time-configuration-variables","title":"Build-time configuration variables","text":"<p>For security reasons - and as per Docker recommendations - Dockerfile-based deploys have variables available only during runtime.</p> <p>For users that require customization in the <code>build</code> phase, you may use build arguments via the docker-options plugin. All environment variables set by the <code>config</code> plugin are automatically exported during a docker build, and thus <code>--build-arg</code> only requires setting a key without a value.</p> <pre><code>dokku docker-options:add node-js-app build '--build-arg NODE_ENV'\n</code></pre> <p>Once set, the Dockerfile usage would be as follows:</p> <pre><code>FROM ubuntu:20.04\n\n# set the argument default\nARG NODE_ENV=production\n\n# use the argument\nRUN echo $NODE_ENV\n</code></pre> <p>You may also set the argument as an environment variable</p> <pre><code>FROM ubuntu:20.04\n\n# set the argument default\nARG NODE_ENV=production\n\n# assign it to an environment variable\n# we can wrap the variable in brackets\nENV NODE_ENV ${NODE_ENV}\n\n# or omit them completely\n\n# use the argument\nRUN echo $NODE_ENV\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#building-images-with-docker-buildkit","title":"Building images with Docker BuildKit","text":"<p>If your Dockerfile is using Docker Engine's BuildKit (not to be confused with buildpacks), then the <code>DOCKER_BUILDKIT=1</code> environment variable needs to be set (unless you're using Docker Engine v24 or higher, which uses BuildKit by default). Additionally, complete build log output can be forced via <code>BUILDKIT_PROGRESS=plain</code>. Both of these environment variables can be set as follows:</p> <pre><code>echo \"export DOCKER_BUILDKIT=1\" | sudo tee -a /etc/default/dokku\necho \"export BUILDKIT_PROGRESS=plain\" | sudo tee -a /etc/default/dokku\n</code></pre>"},{"location":"deployment/builders/dockerfiles/#buildkit-directory-caching","title":"BuildKit directory caching","text":"<p>BuildKit implements the <code>RUN --mount</code> option, enabling mount directory caches for <code>RUN</code> directives. The following is an example that mounts debian packaging related directories, which can speed up fetching of remote package data.</p> <pre><code>FROM debian:latest\nRUN --mount=target=/var/lib/apt/lists,type=cache \\\n    --mount=target=/var/cache/apt,type=cache \\\n    apt-get update \\\n &amp;&amp; DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \\\n      git\n</code></pre> <p>Mount cache targets may vary depending on the tool in use, and users are encouraged to investigate the directories that apply for their language and framework.</p> <p>You would adjust the cache directory for whatever application cache you have, e.g. <code>/root/.pnpm-store/v3</code> for pnpm, <code>$HOME/.m2</code> for maven, or <code>/root/.cache</code> for golang.</p>"},{"location":"deployment/builders/dockerfiles/#customizing-the-run-command","title":"Customizing the run command","text":"<p>By default no arguments are passed to <code>docker run</code> when deploying the container and the <code>CMD</code> or <code>ENTRYPOINT</code> defined in the <code>Dockerfile</code> are executed. You can take advantage of docker ability of overriding the <code>CMD</code> or passing parameters to your <code>ENTRYPOINT</code> setting <code>$DOKKU_DOCKERFILE_START_CMD</code>. Let's say for example you are deploying a base Node.js image, with the following <code>ENTRYPOINT</code>:</p> <pre><code>ENTRYPOINT [\"node\"]\n</code></pre> <p>You can do:</p> <pre><code>dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD=\"--harmony server.js\"\n</code></pre> <p>To tell Docker what to run.</p> <p>Setting <code>$DOKKU_DOCKERFILE_CACHE_BUILD</code> to <code>true</code> or <code>false</code> will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any <code>docker build</code> option to <code>docker</code>, by setting <code>$DOKKU_DOCKER_BUILD_OPTS</code>.</p>"},{"location":"deployment/builders/dockerfiles/#procfiles-and-multiple-processes","title":"Procfiles and multiple processes","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>See the Procfile documentation for more information on how to specify different processes for your app.</p>"},{"location":"deployment/builders/dockerfiles/#exposed-ports","title":"Exposed ports","text":"<p>See the port management documentation for more information on how Dokku exposes ports for applications and how you can configure these for your app.</p>"},{"location":"deployment/builders/herokuish-buildpacks/","title":"Herokuish Buildpacks","text":"<p>New</p> <p>Subcommands introduced in 0.15.0</p> <pre><code>buildpacks:add [--index 1] &lt;app&gt; &lt;buildpack&gt;            # Add new app buildpack while inserting into list of buildpacks if necessary\nbuildpacks:clear &lt;app&gt;                                  # Clear all buildpacks set on the app\nbuildpacks:list &lt;app&gt;                                   # List all buildpacks for an app\nbuildpacks:remove &lt;app&gt; &lt;buildpack&gt;                     # Remove a buildpack set on the app\nbuildpacks:report [&lt;app&gt;] [&lt;flag&gt;]                      # Displays a buildpack report for one or more apps\nbuildpacks:set [--index 1] &lt;app&gt; &lt;buildpack&gt;            # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified\nbuildpacks:set-property [--global|&lt;app&gt;] &lt;key&gt; &lt;value&gt;  # Set or clear a buildpacks property for an app\n</code></pre> <pre><code>builder-herokuish:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-herokuish report for one or more apps\nbuilder-herokuish:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-herokuish property for an app\n</code></pre> <p>Warning</p> <p>If using the <code>buildpacks</code> plugin, be sure to unset any <code>BUILDPACK_URL</code> and remove any such entries from a committed <code>.env</code> file. A specified <code>BUILDPACK_URL</code> will always override a <code>.buildpacks</code> file or the buildpacks plugin.</p> <p>Dokku normally defaults to using Heroku buildpacks for deployment, though this may be overridden by committing a valid <code>Dockerfile</code> to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic <code>Dockerfile</code> deployment detection, you may do one of the following:</p> <ul> <li>Set a <code>BUILDPACK_URL</code> environment variable<ul> <li>This can be done via <code>dokku config:set</code> or via a committed <code>.env</code> file in the root of the repository. See the environment variable documentation for more details.</li> </ul> </li> <li>Create a <code>.buildpacks</code> file in the root of your repository.<ul> <li>This can be via a committed <code>.buildpacks</code> file or managed via the <code>buildpacks</code> plugin commands.</li> </ul> </li> </ul> <p>This page will cover usage of the <code>buildpacks</code> plugin.</p>"},{"location":"deployment/builders/herokuish-buildpacks/#usage","title":"Usage","text":""},{"location":"deployment/builders/herokuish-buildpacks/#detection","title":"Detection","text":"<p>This builder will be auto-detected in either the following cases:</p> <ul> <li>The <code>BUILDPACK_URL</code> app environment variable is set.<ul> <li>This can be done via <code>dokku config:set</code> or via a committed <code>.env</code> file in the root of the repository. See the environment variable documentation for more details.</li> </ul> </li> <li>A <code>.buildpacks</code> file exists in the root of the app repository.<ul> <li>This can be via a committed <code>.buildpacks</code> file or managed via the <code>buildpacks</code> plugin commands.</li> </ul> </li> </ul> <p>The builder can also be specified via the <code>builder:set</code> command:</p> <pre><code>dokku builder:set node-js-app selected herokuish\n</code></pre> <p>Info</p> <p>Dokku will only select the <code>dockerfile</code> builder if both the <code>herokuish</code> and <code>pack</code> builders are not detected and a Dockerfile exists. See the dockerfile builder documentation for more information on how that builder functions.</p>"},{"location":"deployment/builders/herokuish-buildpacks/#listing-buildpacks-in-use","title":"Listing Buildpacks in Use","text":"<p>The <code>buildpacks:list</code> command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.</p> ShellOutputShellOutput <pre><code># running for an app with no buildpacks specified\ndokku buildpacks:list node-js-app\n</code></pre> <pre><code>-----&gt; test buildpack urls\n</code></pre> <pre><code># running for an app with two buildpacks specified\ndokku buildpacks:list node-js-app\n</code></pre> <pre><code>-----&gt; test buildpack urls\n       https://github.com/heroku/heroku-buildpack-python.git\n       https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#adding-custom-buildpacks","title":"Adding custom buildpacks","text":"<p>Info</p> <p>Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.</p> <p>To add a custom buildpack, use the <code>buildpacks:add</code> command:</p> <pre><code>dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre> <p>When no buildpacks are currently specified, the specified buildpack will be the only one executed for detection and compilation.</p> <p>Multiple buildpacks may be specified by using the <code>buildpacks:add</code> command multiple times.</p> <pre><code>dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\ndokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre> <p>Buildpacks are executed in order, may be inserted at a specified index via the <code>--index</code> flag. This flag is specified starting at a 1-index value.</p> <pre><code># will add the golang buildpack at the second position, bumping all proceeding ones by 1 position\ndokku buildpacks:add --index 2 node-js-app https://github.com/heroku/heroku-buildpack-golang.git\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#overwriting-a-buildpack-position","title":"Overwriting a buildpack position","text":"<p>In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the <code>buildpacks:set</code> command can be used to overwrite a buildpack at a given position.</p> <pre><code>dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre> <p>By default, this will overwrite the first buildpack specified. To specify an index, the <code>--index</code> flag may be used. This flag is specified starting at a 1-index value, and defaults to <code>1</code>.</p> <pre><code># the following are equivalent commands\ndokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\ndokku buildpacks:set --index 1 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre> <p>If the index specified is larger than the number of buildpacks currently configured, the buildpack will be appended to the end of the list.</p> <pre><code>dokku buildpacks:set --index 99 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#removing-a-buildpack","title":"Removing a buildpack","text":"<p>Info</p> <p>At least one of a buildpack or index must be specified</p> <p>A single buildpack can be removed by name via the <code>buildpacks:remove</code> command.</p> <pre><code>dokku buildpacks:remove node-js-app https://github.com/heroku/heroku-buildpack-ruby.git\n</code></pre> <p>Buildpacks can also be removed by index via the <code>--index</code> flag. This flag is specified starting at a 1-index value.</p> <pre><code>dokku buildpacks:remove node-js-app --index 1\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#clearing-all-buildpacks","title":"Clearing all buildpacks","text":"<p>Info</p> <p>This does not affect automatically detected buildpacks, nor does it impact any specified <code>BUILDPACK_URL</code> environment variable.</p> <p>The <code>buildpacks:clear</code> command can be used to clear all configured buildpacks for a specified app.</p> <pre><code>dokku buildpacks:clear node-js-app\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#customizing-the-buildpack-stack-builder","title":"Customizing the Buildpack stack builder","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>The default stack builder in use by Herokuish buildpacks in Dokku is based on <code>gliderlabs/herokuish:latest</code>. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the <code>buildpacks:set-property</code> command.</p> <pre><code>dokku buildpacks:set-property node-js-app stack gliderlabs/herokuish:latest\n</code></pre> <p>The specified stack builder can also be unset by omitting the name of the stack builder when calling <code>buildpacks:set-property</code>.</p> <pre><code>dokku buildpacks:set-property node-js-app stack\n</code></pre> <p>A change in the stack builder value will execute the <code>post-stack-set</code> trigger.</p> <p>Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set <code>DOKKU_IMAGE</code> environment variable (<code>gliderlabs/herokuish:latest-22</code> by default).</p> <pre><code># set globally\ndokku buildpacks:set-property --global stack gliderlabs/herokuish:latest\n\n# unset globally\ndokku buildpacks:set-property --global stack\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#allowing-herokuish-for-non-amd64-platforms","title":"Allowing herokuish for non-amd64 platforms","text":"<p>New</p> <p>Introduced in 0.29.0</p> <p>By default, the builder-herokuish plugin is not enabled for non-amd64 platforms, and attempting to use it is blocked. This is because the majority of buildpacks are not cross-platform compatible, and thus building apps will either be considerably slower - due to emulating the amd64 platform - or won't work - due to building amd64 packages on arm64 platforms.</p> <p>To force-enable herokuish on non-amd64 platforms, the <code>allowed</code> property can be set via <code>builder-herokuish:set</code>. The default value depends on the host platform architecture (<code>true</code> on amd64, <code>false</code> otherwise).</p> <pre><code>dokku builder-herokuish:set node-js-app allowed true\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-herokuish:set node-js-app allowed\n</code></pre> <p>The <code>allowed</code> property can also be set globally. The global default is platform-dependent, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-herokuish:set --global allowed true\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-herokuish:set --global allowed\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#displaying-buildpack-reports-for-an-app","title":"Displaying buildpack reports for an app","text":"<p>You can get a report about the app's buildpacks status using the <code>buildpacks:report</code> command:</p> ShellOutput <pre><code>dokku buildpacks:report\n</code></pre> <pre><code>=====&gt; node-js-app buildpacks information\n       Buildpacks computed stack:  gliderlabs/herokuish:v0.7.0-22\n       Buildpacks global stack:    gliderlabs/herokuish:latest-22\n       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git\n       Buildpacks stack:           gliderlabs/herokuish:v0.7.0-20\n=====&gt; python-sample buildpacks information\n       Buildpacks computed stack:  gliderlabs/herokuish:latest-22\n       Buildpacks global stack:    gliderlabs/herokuish:latest-22\n       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git\n       Buildpacks stack:\n=====&gt; ruby-sample buildpacks information\n       Buildpacks computed stack:  gliderlabs/herokuish:latest-22\n       Buildpacks global stack:    gliderlabs/herokuish:latest-22\n       Buildpacks list:\n       Buildpacks stack:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku buildpacks:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app buildpacks information\n       Buildpacks list:               https://github.com/heroku/heroku-buildpack-nodejs.git\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku buildpacks:report node-js-app --buildpacks-list\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#displaying-builder-herokuish-reports-for-an-app","title":"Displaying builder-herokuish reports for an app","text":"<p>New</p> <p>Introduced in 0.29.0</p> <p>You can get a report about the app's storage status using the <code>builder-herokuish:report</code> command:</p> ShellOutput <pre><code>dokku builder-herokuish:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-herokuish information\n       Builder herokuish computed allowed: false\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:          false\n=====&gt; python-sample builder-herokuish information\n       Builder herokuish computed allowed: true\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:\n=====&gt; ruby-sample builder-herokuish information\n       Builder herokuish computed allowed: true\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-herokuish:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-herokuish information\n       Builder herokuish computed allowed: false\n       Builder herokuish global allowed:   true\n       Builder herokuish allowed:          false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-herokuish:report node-js-app --builder-herokuish-allowed\n</code></pre> <pre><code>false\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#errata","title":"Errata","text":""},{"location":"deployment/builders/herokuish-buildpacks/#switching-from-dockerfile-deployments","title":"Switching from Dockerfile deployments","text":"<p>If an application was previously deployed via Dockerfile, the following commands should be run before a buildpack deploy will succeed:</p> <pre><code>dokku ports:clear node-js-app\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#using-a-specific-buildpack-version","title":"Using a specific buildpack version","text":"<p>Info</p> <p>Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.</p> <p>By default, Dokku uses the gliderlabs/herokuish project, which pins all of it's vendored buildpacks. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified without a Git commit SHA like so:</p> <pre><code># using the latest nodejs buildpack\ndokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs\n</code></pre> <p>This will use the latest commit on the <code>master</code> branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form <code>REPOSITORY_URL#COMMIT_SHA</code>, where <code>COMMIT_SHA</code> is any tree-ish git object - usually a git tag.</p> <pre><code># using v87 of the nodejs buildpack\ndokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#curl-build-timeouts","title":"<code>curl</code> build timeouts","text":"<p>Certain buildpacks may time out in retrieving dependencies via <code>curl</code>. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to <code>gzip: stdin: unexpected end of file</code> after a <code>curl</code> command.</p> <p>If you see output similar this when deploying , you may need to override the <code>curl</code> timeouts to increase the length of time allotted to those tasks. You can do so via the <code>config</code> plugin:</p> <pre><code>dokku config:set --global CURL_TIMEOUT=1200\ndokku config:set --global CURL_CONNECT_TIMEOUT=180\n</code></pre>"},{"location":"deployment/builders/herokuish-buildpacks/#clearing-buildpack-cache","title":"Clearing buildpack cache","text":"<p>See the repository management documentation for more information on how to clear buildpack build cache for an application.</p>"},{"location":"deployment/builders/herokuish-buildpacks/#specifying-commands-via-procfile","title":"Specifying commands via Procfile","text":"<p>See the Procfile documentation for more information on how to specify different processes for your app.</p>"},{"location":"deployment/builders/lambda/","title":"Lambda Builder","text":"<p>New</p> <p>Introduced in 0.28.0</p> <pre><code>builder-lambda:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a builder-lambda report for one or more apps\nbuilder-lambda:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a builder-lambda property for an app\n</code></pre> <p>The <code>lambda</code> builder builds AWS Lambda functions in an environment simulating AWS Lambda runtimes via lambda-builder. Apps built via this builder can run natively in Dokku and may also have their artifacts scheduled to Lambda via an appropriate scheduler.</p>"},{"location":"deployment/builders/lambda/#usage","title":"Usage","text":""},{"location":"deployment/builders/lambda/#detection","title":"Detection","text":"<p>This builder will be auto-detected in the following case:</p> <ul> <li>A <code>lambda.yml</code> exists in the root of the app repository.</li> </ul> <p>The builder may also be selected via the <code>builder:set</code> command</p> <pre><code>dokku builder:set node-js-app selected lambda\n</code></pre>"},{"location":"deployment/builders/lambda/#supported-languages","title":"Supported languages","text":"<p>The <code>lambda</code> builder plugin supports the following AWS runtime languages on Amazon Linux 2:</p> <ul> <li>dotnet</li> <li>go (builder is based on AL1)</li> <li>nodejs</li> <li>python</li> <li>ruby</li> </ul> <p>See the lambda-builder documentation for more information on how specific languages are detected.</p>"},{"location":"deployment/builders/lambda/#customizing-the-build-environment","title":"Customizing the build environment","text":"<p>The <code>lambda</code> builder plugin delegates all build logic to lambda-builder, including language detection and build/runtime environment specification. The lambda-builder tool supports a <code>lambda.yml</code> file format for customizing how apps are built. Please see the readme for lambda-builder for more information on different options.</p>"},{"location":"deployment/builders/lambda/#changing-the-lambdayml-location","title":"Changing the <code>lambda.yml</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>lambda.yml</code> file to use for a given app. This can be done via the <code>builder-lambda:set</code> command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>lambda.yml</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>lambda.yml</code> extracted directly from the source code. Both cases will respect the configured <code>lambdayml-path</code> property value.</p> <pre><code>dokku builder-lambda:set node-js-app lambdayml-path .dokku/lambda.yml\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-lambda:set node-js-app lambdayml-path\n</code></pre> <p>The <code>lambdayml-path</code> property can also be set globally. The global default is <code>lambda.yml</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-lambda:set --global lambdayml-path lambda2.yml\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-lambda:set --global lambdayml-path\n</code></pre>"},{"location":"deployment/builders/lambda/#displaying-builder-lambda-reports-for-an-app","title":"Displaying builder-lambda reports for an app","text":"<p>You can get a report about the app's storage status using the <code>builder-lambda:report</code> command:</p> ShellOutput <pre><code>dokku builder-lambda:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-lambda information\n       Builder lambda computed lambdayml path: lambda2.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:          lambda2.yml\n=====&gt; python-sample builder-lambda information\n       Builder lambda computed lambdayml path: lambda.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:\n=====&gt; ruby-sample builder-lambda information\n       Builder lambda computed lambdayml path: lambda.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-lambda:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-lambda information\n       Builder lambda computed lambdayml path: lambda2.yml\n       Builder lambda global lambdayml path:   lambda.yml\n       Builder lambda lambdayml path:          lambda2.yml\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-lambda:report node-js-app --builder-lambda-lambdayml-path\n</code></pre> <pre><code>lambda2.yml\n</code></pre>"},{"location":"deployment/builders/nixpacks/","title":"Nixpacks","text":"<p>New</p> <p>Introduced in 0.32.0</p> <p>The <code>nixpacks</code> builder builds apps via Nixpacks, a buildpack alternative.</p>"},{"location":"deployment/builders/nixpacks/#usage","title":"Usage","text":""},{"location":"deployment/builders/nixpacks/#requirements","title":"Requirements","text":"<p>The <code>nixpacks</code> cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on this page.</p> <p>Builds will proceed with the <code>nixpacks</code> cli for the app from then on.</p>"},{"location":"deployment/builders/nixpacks/#detection","title":"Detection","text":"<p>This builder will be auto-detected in the following case:</p> <ul> <li>A <code>nixpacks.toml</code> exists in the root of the app repository.</li> </ul> <p>The builder may also be selected via the <code>builder:set</code> command</p> <pre><code>dokku builder:set node-js-app selected nixpacks\n</code></pre>"},{"location":"deployment/builders/nixpacks/#supported-languages","title":"Supported languages","text":"<p>See the upstream nixpacks documentation for further information on what languages and frameworks are supported.</p>"},{"location":"deployment/builders/nixpacks/#build-time-configuration-variables","title":"Build-time configuration variables","text":"<p>For security reasons - and as per Docker recommendations - nixpacks-based deploys have variables available only during runtime.</p> <p>For users that require customization in the <code>build</code> phase, you may use build arguments via the docker-options plugin. All environment variables set by the <code>config</code> plugin are automatically exported within the nixpacks build environment, and thus <code>--env</code> only requires setting a key without a value.</p> <pre><code>dokku docker-options:add node-js-app build '--env NODE_ENV'\n</code></pre> <p>Alternatively, a full value may be provided in the form of <code>--env KEY=VALUE</code>:</p> <pre><code>dokku docker-options:add node-js-app build '--env NODE_ENV=production'\n</code></pre>"},{"location":"deployment/builders/nixpacks/#changing-the-nixpackstoml-location","title":"Changing the <code>nixpacks.toml</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>nixpacks.toml</code> file to use for a given app. This can be done via the <code>builder-nixpacks:set</code> command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.</p> <pre><code>dokku builder-nixpacks:set node-js-app nixpackstoml-path nixpacks2.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-nixpacks:set node-js-app nixpackstoml-path\n</code></pre> <p>The <code>nixpackstoml-path</code> property can also be set globally. The global default is <code>nixpacks.toml</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-nixpacks:set --global nixpackstoml-path nixpacks2.toml\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-nixpacks:set --global nixpackstoml-path\n</code></pre>"},{"location":"deployment/builders/nixpacks/#disabling-cache","title":"Disabling cache","text":"<p>Cache is enabled by default, but can be disabled by setting the <code>no-cache</code> property to <code>true</code>:</p> <pre><code>dokku builder-nixpacks:set node-js-app no-cache true\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku builder-nixpacks:set node-js-app no-cache\n</code></pre> <p>The <code>no-cache</code> property can also be set globally. The global default is <code>false</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku builder-nixpacks:set --global no-cache true\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku builder-nixpacks:set --global no-cache\n</code></pre>"},{"location":"deployment/builders/nixpacks/#displaying-builder-nixpacks-reports-for-an-app","title":"Displaying builder-nixpacks reports for an app","text":"<p>You can get a report about the app's storage status using the <code>builder-nixpacks:report</code> command:</p> ShellOutput <pre><code>dokku builder-nixpacks:report\n</code></pre> <pre><code>=====&gt; node-js-app builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks2.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:          nixpacks2.toml\n       Builder-nixpacks computed no cache:          true\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:                   true\n=====&gt; python-sample builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:\n       Builder-nixpacks computed no cache:          false\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:\n=====&gt; ruby-sample builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:\n       Builder-nixpacks computed no cache:          false\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku builder-nixpacks:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app builder-nixpacks information\n       Builder-nixpacks computed nixpackstoml path: nixpacks2.toml\n       Builder-nixpacks global nixpackstoml path:   nixpacks.toml\n       Builder-nixpacks nixpackstoml path:          nixpacks2.toml\n       Builder-nixpacks computed no cache:          true\n       Builder-nixpacks global no cache:            false\n       Builder-nixpacks no cache:                   true\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> ShellOutput <pre><code>dokku builder-nixpacks:report node-js-app --builder-nixpacks-no-cache\n</code></pre> <pre><code>true\n</code></pre>"},{"location":"deployment/builders/null/","title":"Null Builder","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>The <code>null</code> builder does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the network documentation for more information on the aforementioned use case.</p>"},{"location":"deployment/builders/null/#usage","title":"Usage","text":""},{"location":"deployment/builders/null/#detection","title":"Detection","text":"<p>This builder is never auto-detected. The builder must  be specified via the <code>builder:set</code> command:</p> <pre><code>dokku builder:set node-js-app selected null\n</code></pre>"},{"location":"deployment/continuous-integration/generic/","title":"Generic CI/CD Integration","text":"<p>In cases where there is no direct or documented integration available, the Dokku project provides an Official Docker Image for use in Continuous Integration/Continuous Deployment (CI/CD) systems.</p> <p>Assuming a Docker image can be run as a CI task with environment variables injected, the following CI systems will have their variables automatically detected:</p> <ul> <li>circleci</li> <li>cloudbees</li> <li>drone</li> <li>github actions</li> <li>gitlab-ci</li> <li>semaphoreci</li> <li>travisci</li> </ul>"},{"location":"deployment/continuous-integration/generic/#simple-usage","title":"Simple Usage","text":"<p>The simplest usage of the image is as follows.</p> <pre><code># where the `.env` file contains `GIT_REMOTE_URL` and `SSH_PRIVATE_KEY`\n\ndocker run --rm -v=\"$PWD:/app\" --env-file=.env dokku/ci-docker-image dokku-deploy\n</code></pre> <p>For more configuration examples and further documentation, see the ci-docker-image readme.</p>"},{"location":"deployment/continuous-integration/github-actions/","title":"GitHub Actions","text":"<p>The Dokku project has an official GitHub Action available on the GitHub Marketplace. The simplest usage example is as follows:</p> <pre><code>---\nname: 'deploy'\n\non:\n  push:\n    branches:\n      - master\n\njobs:\n  deploy:\n    runs-on: ubuntu-22.04\n    steps:\n      - name: Cloning repo\n        uses: actions/checkout@v3\n        with:\n          fetch-depth: 0\n\n      - name: Push to dokku\n        uses: dokku/github-action@master\n        with:\n          git_remote_url: 'ssh://dokku@dokku.me:22/appname'\n          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}\n</code></pre> <p>For further usage documentation and other advanced examples, see the entry on the GitHub Marketplace.</p>"},{"location":"deployment/continuous-integration/gitlab-ci/","title":"GitLab CI","text":"<p>GitLab CI can be used to automatically deploy a Dokku application via the official the dokku/ci-docker-image. The simplest example is as follows:</p> <pre><code>---\nimage: dokku/ci-docker-image\n\nstages:\n  - deploy\n\nvariables:\n  GIT_DEPTH: 0\n\ndeploy:\n  stage: deploy\n  only:\n    - master\n  variables:\n    GIT_REMOTE_URL: ssh://dokku@dokku.me:22/appname\n  script: \n    - dokku-deploy\n  after_script: \n    - dokku-unlock\n</code></pre> <p>For further usage documentation and other advanced examples, see Dokku's gitlab-ci repository.</p>"},{"location":"deployment/methods/archive/","title":"Tar and Zip Archives","text":""},{"location":"deployment/methods/archive/#initializing-an-app-repository-from-an-archive-file","title":"Initializing an app repository from an archive file","text":"<p>New</p> <p>Introduced in 0.24.0</p> <p>A Dokku app repository can be initialized or updated from the contents of an archive file via the <code>git:from-archive</code> command. This is an excellent way of tracking changes when deploying pre-built binary archives, such as java jars or go binaries. This can also be useful when deploying directly from a GitHub repository at a specific commit.</p> <pre><code>dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar\n</code></pre> <p>In the above example, Dokku will build the app as if the repository contained the extracted contents of the specified archive file.</p> <p>Triggering a build with the same archive file multiple times will result in Dokku exiting <code>0</code> early as there will be no changes detected.</p> <p>The <code>git:from-archive</code> command can optionally take a git <code>user.name</code> and <code>user.email</code> argument (in that order) to customize the author. If the arguments are left empty, they will fallback to <code>Dokku</code> and <code>automated@dokku.sh</code>, respectively.</p> <pre><code>dokku git:from-archive node-js-app https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar \"Camila\" \"camila@example.com\"\n</code></pre> <p>The default archive type is always set to <code>.tar</code>. To use a different archive type, specify the <code>--archive-type</code> flag. Failure to do so will result in a failure to extract the archive.</p> <pre><code>dokku git:from-archive --archive-type zip node-js-app https://github.com/dokku/smoke-test-app/archive/2.0.0.zip \"Camila\" \"camila@example.com\"\n</code></pre> <p>Finally, if the archive url is specified as <code>--</code>, the archive will be fetched from stdin.</p> <pre><code>curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar | dokku git:from-archive node-js-app  --\n</code></pre>"},{"location":"deployment/methods/git/","title":"Git Deployment","text":"<p>New</p> <p>Subcommands introduced in 0.12.0</p> <pre><code>git:allow-host &lt;host&gt;                             # Adds a host to known_hosts\ngit:auth &lt;host&gt; [&lt;username&gt; &lt;password&gt;]           # Configures netrc authentication for a given git server\ngit:from-archive [--archive-type ARCHIVE_TYPE] &lt;app&gt; &lt;archive-url&gt; [&lt;git-username&gt; &lt;git-email&gt;] # Updates an app's git repository with a given archive file\ngit:from-image [--build-dir DIRECTORY] &lt;app&gt; &lt;docker-image&gt; [&lt;git-username&gt; &lt;git-email&gt;] # Updates an app's git repository with a given docker image\ngit:generate-deploy-key                           # Generates a deploy ssh key\ngit:load-image [--build-dir DIRECTORY] &lt;app&gt; &lt;docker-image&gt; [&lt;git-username&gt; &lt;git-email&gt;] # Updates an app's git repository with a docker image loaded from stdin\ngit:sync [--build] &lt;app&gt; &lt;repository&gt; [&lt;git-ref&gt;] # Clone or fetch an app from remote git repo\ngit:initialize &lt;app&gt;                              # Initialize a git repository for an app\ngit:public-key                                    # Outputs the dokku public deploy key\ngit:report [&lt;app&gt;] [&lt;flag&gt;]                       # Displays a git report for one or more apps\ngit:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)                     # Set or clear a git property for an app\ngit:status &lt;app&gt;                                  # Show the working tree status for an app\ngit:unlock &lt;app&gt; [--force]                        # Removes previous git clone folder for new deployment\n</code></pre> <p>Git-based deployment has been the traditional method of deploying applications in Dokku. As of v0.12.0, Dokku introduces a few ways to customize the experience of deploying via <code>git push</code>. A Git-based deployment currently supports building applications via:</p> <ul> <li>Cloud Native Buildpacks</li> <li>Herokuish Buildpack</li> <li>Dockerfiles</li> </ul>"},{"location":"deployment/methods/git/#usage","title":"Usage","text":"<p>Warning</p> <p>Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process.</p>"},{"location":"deployment/methods/git/#initializing-an-application","title":"Initializing an application","text":"<p>When an application is created via <code>git push</code>, Dokku will create the proper <code>pre-receive</code> hook in order to execute the build pipeline. In certain cases - such as when fronting deploys with the <code>git-http-backend</code> - this may not be correctly created. As an alternative, the <code>git:initialize</code> command can be used to trigger this creation:</p> <pre><code># on the Dokku host\n\n# overrides any existing pre-receive hook\ndokku git:initialize node-js-app\n</code></pre> <p>In order for the above command to succeed, the application must already exist.</p> <p>Warning</p> <p>If the <code>pre-receive</code> hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.</p>"},{"location":"deployment/methods/git/#changing-the-deploy-branch","title":"Changing the deploy branch","text":"<p>By default, Dokku will deploy code pushed to the <code>master</code> branch. In order to quickly deploy a different local branch, the following Git command can be used:</p> <pre><code># on the local machine\n\n# where `SOME_BRANCH_NAME` is the name of the branch\ngit push dokku SOME_BRANCH_NAME:master\n</code></pre> <p>In <code>0.12.0</code>, the correct way to change the deploy branch is to use the <code>git:set</code> Dokku command.</p> <pre><code># on the Dokku host\n\n# override for all applications\ndokku git:set --global deploy-branch SOME_BRANCH_NAME\n\n# override for a specific app\n# where `SOME_BRANCH_NAME` is the name of the branch\ndokku git:set node-js-app deploy-branch SOME_BRANCH_NAME\n</code></pre> <p>As of 0.22.1, Dokku will also respect the first pushed branch as the primary branch, and automatically set the <code>deploy-branch</code> value at that time.</p> <p>Pushing multiple branches can also be supported by creating a receive-branch plugin trigger in a custom plugin.</p>"},{"location":"deployment/methods/git/#configuring-the-git_rev-environment-variable","title":"Configuring the <code>GIT_REV</code> environment variable","text":"<p>New</p> <p>Introduced in 0.12.0</p> <p>Application deployments will include a special <code>GIT_REV</code> environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same.</p> <p>To configure the name of the <code>GIT_REV</code> environment variable, run the <code>git:set</code> command as follows:</p> <pre><code># on the Dokku host\n\n# override for a specific app\ndokku git:set node-js-app rev-env-var DOKKU_GIT_REV\n</code></pre> <p>This behavior can be disabled entirely on a per-app basis by setting the <code>rev-env-var</code> value to an empty string:</p> <pre><code># on the Dokku host\n\n# override for a specific app\ndokku git:set node-js-app rev-env-var \"\"\n</code></pre>"},{"location":"deployment/methods/git/#keeping-the-git-directory","title":"Keeping the <code>.git</code> directory","text":"<p>By default, Dokku will remove the contents of the <code>.git</code> before triggering a build for a given app. This is generally a safe default as shipping the entire source code history of your app in the deployed image artifact is unnecessary as it increases bloat and potentially can leak information if there are any security issues with your app code.</p> <p>To enable the <code>.git</code> directory, run the <code>git:set</code> command as follows:</p> <pre><code># on the Dokku host\n\n# keep the .git directory during builds\ndokku git:set node-js-app keep-git-dir true\n</code></pre> <p>The default behavior is to delete this directory and it's contents. To revert to the default behavior, the <code>keep-git-dir</code> value can be set to either an empty string or <code>false</code>.</p> <pre><code># on the Dokku host\n\n# delete the .git directory during builds (default)\ndokku git:set node-js-app keep-git-dir false\n\n# delete the .git directory during builds (default)\ndokku git:set node-js-app keep-git-dir \"\"\n</code></pre> <p>Please keep in mind that setting <code>keep-git-dir</code> to <code>true</code> may result in unstaged changes shown within the built container due to the build process generating application changes within the built app directory.</p>"},{"location":"deployment/methods/git/#initializing-an-app-repository-from-a-remote-repository","title":"Initializing an app repository from a remote repository","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>A Dokku app repository can be initialized or updated from a remote git repository via the <code>git:sync</code> command. This command will either clone or fetch updates from a remote repository and has undefined behavior if the history cannot be fast-fowarded to the referenced repository reference. Any repository that can be cloned by the <code>dokku</code> user can be specified.</p> <p>Info</p> <p>The application must exist before the repository can be initialized</p> <pre><code>dokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git\n</code></pre> <p>The <code>git:sync</code> command optionally takes an optional third parameter containing a git reference, which may be a branch, tag, or specific commit.</p> <pre><code># specify a branch\ndokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git main\n\n# specify a tag\ndokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git 1\n\n# specify a commit\ndokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git 97e6c72491c7531507bfc5413903e0e00e31e1b0\n</code></pre> <p>By default, this command does not trigger an application build. To do so during a <code>git:sync</code>, specify the <code>--build</code> flag.</p> <pre><code>dokku git:sync --build node-js-app https://github.com/heroku/node-js-getting-started.git\n</code></pre>"},{"location":"deployment/methods/git/#initializing-from-private-repositories","title":"Initializing from private repositories","text":"<p>New</p> <p>Introduced in 0.24.0</p> <p>Initializing from a private repository requires one of the following:</p> <ul> <li>A Public SSH Key (<code>id_rsa.pub</code> file) configured on the remote server, with the associated private key (<code>id_rsa</code>) in the Dokku server's <code>/home/dokku/.ssh/</code> directory.</li> <li>A configured <code>.netrc</code> entry.</li> </ul> <p>Dokku provides the <code>git:auth</code> command which can be used to configure a <code>netrc</code> entry for the remote server. This command can be used to add or remove configuration for any remote server.</p> <pre><code># add credentials for github.com\ndokku git:auth github.com username personal-access-token\n\n# remove credentials for github.com\ndokku git:auth github.com\n</code></pre> <p>For syncing to a private repository stored on a remote Git product such as GitHub or GitLab, Dokku's recommendation is to use a personal access token on a bot user where possible. Please see your service's documentation for information regarding the recommended best practices.</p>"},{"location":"deployment/methods/git/#allowing-remote-repository-hosts","title":"Allowing remote repository hosts","text":"<p>By default, the Dokku host may not have access to a server containing the remote repository. This can be initialized via the <code>git:allow-host</code> command.</p> <pre><code>dokku git:allow-host github.com\n</code></pre> <p>Note that this command is currently not idempotent and may add duplicate entries to the <code>~dokku/.ssh/known_hosts</code> file.</p>"},{"location":"deployment/methods/git/#creating-a-cloning-ssh-key-pair","title":"Creating a cloning ssh key pair","text":"<p>New</p> <p>Introduced in 0.33.0</p> <p>While most repositories can be authenticated to via the <code>git:auth</code> command, some users may prefer to use an ssh key. This can be generated via the <code>git:generate-deploy-key</code> command, which generates a passwordless ed25519 key-pair.</p> ShellOutput <pre><code>dokku git:generate-deploy-key\n</code></pre> <pre><code>Generating public/private ed25519 key pair.\nYour identification has been saved in /home/dokku/.ssh/id_ed25519\nYour public key has been saved in /home/dokku/.ssh/id_ed25519.pub\nThe key fingerprint is:\nSHA256:PvlvVfbpYvkmA87rTfLUq07e3GarRN1BcLqDSjod+p8 dokku@ubuntu\nThe key's randomart image is:\n+--[ED25519 256]--+\n|             ..o |\n|              +  |\n|             . . |\n|            . o =|\n|        So . + ++|\n|       .=.o.. +..|\n|       ++oo..*o. |\n|        oo o%*oo=|\n|         .+E=BOOo|\n+----[SHA256]-----+\n</code></pre>"},{"location":"deployment/methods/git/#verifying-the-cloning-public-key","title":"Verifying the cloning public key","text":"<p>In order to clone a remote repository, the remote server should have the Dokku host's public key configured. This plugin does not currently create this key, but if can be shown via the <code>git:public-key</code> command.</p> <pre><code>dokku git:public-key\n</code></pre> <p>If there is no key, an error message is shown that displays the command that can be run on the Dokku server to generate a new public/private ssh key pair.</p>"},{"location":"deployment/methods/image/","title":"Docker Image Deployment","text":""},{"location":"deployment/methods/image/#initializing-an-app-repository-from-a-docker-image","title":"Initializing an app repository from a docker image","text":"<p>New</p> <p>Introduced in 0.24.0</p> <p>A Dokku app repository can be initialized or updated from a Docker image via the <code>git:from-image</code> command. This command will either initialize the app repository or update it to include the specified Docker image via a <code>FROM</code> stanza. This is an excellent way of tracking changes when deploying only a given docker image, especially if deploying an image from a remote CI/CD pipeline.</p> <pre><code>dokku git:from-image node-js-app my-registry/node-js-getting-started:latest\n</code></pre> <p>In the above example, Dokku will build the app as if the repository contained only a <code>Dockerfile</code> with the following content:</p> <pre><code>FROM my-registry/node-js-getting-started:latest\n</code></pre> <p>If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using build phase docker-options.</p> <p>Triggering a build with the same arguments multiple times will result in Dokku exiting <code>0</code> early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:</p> <pre><code># for images pushed to a remote registry\ndocker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME\n\n# for images built locally and not pushed to a registry\n# use when the previous command output is empty\ndocker images --no-trunc --quiet $IMAGE_NAME\n</code></pre> <p>The resulting <code>git:from-image</code> call would then be:</p> <pre><code># where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\ndokku git:from-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\n</code></pre> <p>The <code>git:from-image</code> command can optionally take a git <code>user.name</code> and <code>user.email</code> argument (in that order) to customize the author. If the arguments are left empty, they will fallback to <code>Dokku</code> and <code>automated@dokku.sh</code>, respectively.</p> <pre><code>dokku git:from-image node-js-app my-registry/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>If the image is a private image that requires a docker login to access, the <code>registry:login</code> command should be used to log into the registry. See the registry documentation for more details on this process.</p> <p>Finally, certain images may require a custom build context in order for <code>ONBUILD ADD</code> and <code>ONBUILD COPY</code> statements to succeed. A custom build context can be specified via the <code>--build-dir</code> flag. All files in the specified <code>build-dir</code> will be copied into the repository for use within the <code>docker build</code> process. The build context must be specified on each deploy, and is not otherwise persisted between builds.</p> <pre><code>dokku git:from-image --build-dir path/to/build node-js-app domy-registrykku/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>See the dockerfile documentation to learn about the different ways to configure Dockerfile-based deploys.</p>"},{"location":"deployment/methods/image/#initializing-an-app-repository-from-a-remote-image-without-a-registry","title":"Initializing an app repository from a remote image without a registry","text":"<p>New</p> <p>Introduced in 0.30.0</p> <p>A Dokku app repository can be initialized or updated from the contents of an image archive tar file via the <code>git:load-image</code> command. This method can be used when a Docker Registry is unavailable to act as an intermediary for storing an image, such as when building an image in CI and deploying directly from that image.</p> <pre><code>docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest\n</code></pre> <p>In the above example, we are saving the image to a tar file via <code>docker image save</code>, streaming that to the Dokku host, and then running <code>git:load-image</code> on the incoming stream. Dokku will build the app as if the repository contained only a <code>Dockerfile</code> with the following content:</p> <pre><code>FROM my-registry/node-js-getting-started:latest\n</code></pre> <p>When deploying an app via <code>git:load-image</code>, it is highly recommended to use a unique image tag when building the image. Not doing so will result in Dokku exiting <code>0</code> early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:</p> <pre><code># for images pushed to a remote registry\ndocker inspect --format='{{index .RepoDigests 0}}' $IMAGE_NAME\n\n# for images built locally and not pushed to a registry\n# use when the previous command output is empty\ndocker images --no-trunc --quiet $IMAGE_NAME\n</code></pre> <p>The resulting <code>git:load-image</code> call would then be:</p> <pre><code># where the image sha is: sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\ndocker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started@sha256:9d187c3025d03c033dcc71e3a284fee53be88cc4c0356a19242758bc80cab673\n</code></pre> <p>The <code>git:load-image</code> command can optionally take a git <code>user.name</code> and <code>user.email</code> argument (in that order) to customize the author. If the arguments are left empty, they will fallback to <code>Dokku</code> and <code>automated@dokku.sh</code>, respectively.</p> <pre><code>docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app my-registry/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>Finally, certain images may require a custom build context in order for <code>ONBUILD ADD</code> and <code>ONBUILD COPY</code> statements to succeed. A custom build context can be specified via the <code>--build-dir</code> flag. All files in the specified <code>build-dir</code> will be copied into the repository for use within the <code>docker build</code> process. The build context must be specified on each deploy, and is not otherwise persisted between builds.</p> <pre><code>docker image save my-registry/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image --build-dir path/to/build node-js-app my-registry/node-js-getting-started:latest \"Camila\" \"camila@example.com\"\n</code></pre> <p>See the dockerfile documentation to learn about the different ways to configure Dockerfile-based deploys.</p>"},{"location":"deployment/schedulers/docker-local/","title":"Docker Local Scheduler","text":"<p>New</p> <p>Subcommands introduced in 0.12.12</p> <pre><code>scheduler-docker-local:report [&lt;app&gt;] [&lt;flag&gt;]              # Displays a scheduler-docker-local report for one or more apps\nscheduler-docker-local:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)            # Set or clear a scheduler-docker-local property for an app\n</code></pre> <p>New</p> <p>Introduced in 0.12.0</p> <p>Dokku natively includes functionality to manage application lifecycles for a single server using the <code>scheduler-docker-local</code> plugin. It is the default scheduler, but as with all schedulers, it is set on a per-application basis. The scheduler can currently be overridden by running the following command:</p> <pre><code>dokku scheduler:set node-js-app selected docker-local\n</code></pre> <p>As it is the default, unsetting the <code>selected</code> scheduler property is also a valid way to reset the scheduler.</p> <pre><code>dokku scheduler:set node-js-app selected\n</code></pre>"},{"location":"deployment/schedulers/docker-local/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/docker-local/#deploying-amd64-images-on-arm64","title":"Deploying amd64 images on arm64","text":"<p>New</p> <p>Introduced in 0.33.0</p> <p>Many builders only produce amd64-compatible images. The docker-local scheduler will automatically detect these and run them via the <code>--platform=linux/amd64</code> on arm64 deploy targets.</p>"},{"location":"deployment/schedulers/docker-local/#disabling-chown-of-persistent-storage","title":"Disabling chown of persistent storage","text":"<p>The <code>scheduler-docker-local</code> plugin will ensure your storage mounts are owned by either <code>herokuishuser</code> or the overridden value you have set in <code>DOKKU_APP_USER</code>. You may disable this by running the following <code>scheduler-docker-local:set</code> command for your application:</p> <pre><code>dokku scheduler-docker-local:set node-js-app disable-chown true\n</code></pre> <p>Once set, you may re-enable it by setting a blank value for <code>disable-chown</code>:</p> <pre><code>dokku scheduler-docker-local:set node-js-app disable-chown\n</code></pre>"},{"location":"deployment/schedulers/docker-local/#disabling-the-init-process","title":"Disabling the init process","text":"<p>The <code>scheduler-docker-local</code> injects an init process by default via the <code>--init</code>. For some apps - such as those where the built docker image uses S6 as the init - this may be undesirable and cause issues with process starts. You may disable this by running the following <code>scheduler-docker-local:set</code> command for your application:</p> <pre><code>dokku scheduler-docker-local:set node-js-app init-process false\n</code></pre> <p>Once set, you may re-enable it by setting a blank value for <code>init-process</code>:</p> <pre><code>dokku scheduler-docker-local:set node-js-app init-process\n</code></pre> <p>All image containers with the label <code>org.opencontainers.image.vendor=linuxserver.io</code> will have the automatic init process injection force-disabled without further intervention.</p>"},{"location":"deployment/schedulers/docker-local/#deploying-process-types-in-parallel","title":"Deploying Process Types in Parallel","text":"<p>New</p> <p>Introduced in 0.25.5</p> <p>By default, Dokku deploys an app's processes one-by-one in order, with the <code>web</code> process being deployed first. Deployment parallelism may be achieved by setting the <code>parallel-schedule-count</code> property, which defaults to <code>1</code>. Increasing this number increases the number of process types that may be deployed in parallel (with the web process being the exception).</p> <pre><code># Increase parallelism from 1 process type at a time to 4 process types at a time.\ndokku scheduler-docker-local:set node-js-app parallel-schedule-count 4\n</code></pre> <p>Once set, you may reset it by setting a blank value for <code>parallel-schedule-count</code>:</p> <pre><code>dokku scheduler-docker-local:set node-js-app parallel-schedule-count\n</code></pre> <p>If the value of <code>parallel-schedule-count</code> is increased and a given process type fails to schedule successfully, then any in-flight process types will continue to be processed, while all process types that have not been scheduled will be skipped before the deployment finally fails.</p> <p>Container scheduling output is shown in the order it is received, and thus may be out of order in case of output to stderr.</p> <p>Note that increasing the value of <code>parallel-schedule-count</code> may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.</p>"},{"location":"deployment/schedulers/docker-local/#increasing-parallelism-within-a-process-deploy","title":"Increasing parallelism within a process deploy","text":"<p>New</p> <p>Introduced in 0.26.0</p> <p>By default, Dokku will deploy one instance of a given process type at a time. This can be increased by customizing the <code>app.json</code> <code>formation</code> key to include a <code>max_parallel</code> key for the given process type.</p> <p>The <code>formation</code> key should be specified as follows in the <code>app.json</code> file:</p> <pre><code>{\n  \"formation\": {\n    \"web\": {\n      \"max_parallel\": 1\n    },\n    \"worker\": {\n      \"max_parallel\": 4\n    }\n  }\n}\n</code></pre> <p>Omitting or removing the entry will result in parallelism for that process type to return to 1 entry at a time. This can be combined with the <code>parallel-schedule-count</code> property to speed up deployments.</p> <p>Note that increasing the value of <code>max_parallel</code> may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.</p> <p>See the app.json location documentation for more information on where to place your <code>app.json</code> file.</p>"},{"location":"deployment/schedulers/docker-local/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented scheduler functionality for the <code>docker-local</code> scheduler.</p>"},{"location":"deployment/schedulers/docker-local/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the <code>scheduler-docker-local</code> plugin.</p> <ul> <li><code>apps:clone</code></li> <li><code>apps:destroy</code></li> <li><code>apps:rename</code></li> <li><code>deploy</code></li> <li><code>enter</code></li> <li><code>logs</code></li> <li><code>ps:inspect</code></li> <li><code>ps:stop</code></li> <li><code>run</code></li> </ul>"},{"location":"deployment/schedulers/docker-local/#logging-support","title":"Logging support","text":"<p>App logs for the <code>logs</code> command are fetched from running containers via the <code>docker</code> cli. To persist logs across deployments, consider using Dokku's vector integration to ship logs to another service or a third-party platform.</p>"},{"location":"deployment/schedulers/docker-local/#supported-resource-management-properties","title":"Supported Resource Management Properties","text":"<p>The <code>docker-local</code> scheduler supports a minimal list of resource limits and reservations. The following properties are supported:</p>"},{"location":"deployment/schedulers/docker-local/#resource-limits","title":"Resource Limits","text":"<ul> <li>cpu: (docker option: <code>--cpus</code>), is specified in number of CPUs a process can access.<ul> <li>See the \"CPU\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> <li>memory: (docker option: <code>--memory</code>) should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).<ul> <li>See the \"Memory\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> <li>memory-swap: (docker option: <code>--memory-swap</code>) should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes)<ul> <li>See the \"Memory\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> <li>nvidia-gpus: (docker option: <code>--gpus</code>), is specified in number of Nvidia GPUs a process can access.<ul> <li>See the \"GPU\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> </ul>"},{"location":"deployment/schedulers/docker-local/#resource-reservations","title":"Resource Reservations","text":"<ul> <li>memory: (docker option: <code>--memory-reservation</code>) should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).<ul> <li>See the \"Memory\" section of the Docker Runtime Options documentation for more information.</li> </ul> </li> </ul>"},{"location":"deployment/schedulers/k3s/","title":"K3s Scheduler","text":"<p>New</p> <p>Introduced in 0.33.0</p> <pre><code>scheduler-k3s:cluster-add [ssh://user@host:port]    # Adds a server node to a Dokku-managed cluster\nscheduler-k3s:cluster-list                          # Lists all nodes in a Dokku-managed cluster\nscheduler-k3s:cluster-remove [node-id]              # Removes client node to a Dokku-managed cluster\nscheduler-k3s:initialize                            # Initializes a cluster\nscheduler-k3s:report [&lt;app&gt;] [&lt;flag&gt;]               # Displays a scheduler-k3s report for one or more apps\nscheduler-k3s:set [&lt;app&gt;|--global] &lt;key&gt; (&lt;value&gt;)  # Set or clear a scheduler-k3s property for an app or the scheduler\nscheduler-k3s:show-kubeconfig                       # Displays the kubeconfig for remote usage\nscheduler-k3s:uninstall                             # Uninstalls k3s from the Dokku server\n</code></pre> <p>Note</p> <p>The k3s plugin replaces the external scheduler-kubernetes plugin. Users can continue to use the external plugin as necessary, but all future development will occur on the official core k3s plugin.</p> <p>For multi-server support, Dokku provides the ability for users to setup a K3s cluster. As with all schedulers, it is set on a per-app basis. The scheduler can currently be overridden by running the following command:</p> <pre><code>dokku scheduler:set node-js-app selected k3s\n</code></pre> <p>As it is the default, unsetting the <code>selected</code> scheduler property is also a valid way to reset the scheduler.</p> <pre><code>dokku scheduler:set node-js-app k3s\n</code></pre>"},{"location":"deployment/schedulers/k3s/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/k3s/#initializing-a-cluster","title":"Initializing a cluster","text":"<p>Warning</p> <p>This command must be run as root</p> <p>Clusters can be initialized via the <code>scheduler-k3s:initialize</code> command. This will start a k3s cluster on the Dokku node itself.</p> <pre><code>dokku scheduler-k3s:initialize\n</code></pre> <p>By default, the k3s installation can run both app and system workloads. For clusters where app workloads are run on distinct worker nodes, initialize the cluster with the <code>--taint-scheduling</code> flag, which will allow only Critical cluster components on the k3s control-plane nodes.</p> <pre><code>dokku scheduler-k3s:initialize --taint-scheduling\n</code></pre> <p>By default, Dokku will attempt to auto-detect the IP address of the server. In cases where the auto-detected IP address is incorrect, an override may be specified via the <code>--server-ip</code> flag:</p> <pre><code>dokku scheduler-k3s:initialize --server-ip 192.168.20.15\n</code></pre>"},{"location":"deployment/schedulers/k3s/#adding-nodes-to-the-cluster","title":"Adding nodes to the cluster","text":"<p>Warning</p> <p>The <code>dokku</code> user must be able to ssh onto the server in order to connect nodes to the cluster. The remote user must be root or have sudo enabled, or the install will fail.</p>"},{"location":"deployment/schedulers/k3s/#adding-a-worker-node","title":"Adding a worker node","text":"<p>Nodes that run app workloads can be added via the <code>scheduler-k3s:cluster-add</code> command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.</p> <pre><code>dokku scheduler-k3s:cluster-add  ssh://root@worker-1.example.com\n</code></pre> <p>If the server isn't in the <code>known_hosts</code> file, the connection will fail. This can be bypassed by setting the <code>--insecure-allow-unknown-hosts</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --insecure-allow-unknown-hosts ssh://root@worker-1.example.com\n</code></pre> <p>By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the <code>--server-ip</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --server-ip 192.168.20.15 ssh://root@worker-1.example.com\n</code></pre>"},{"location":"deployment/schedulers/k3s/#adding-a-server-node","title":"Adding a server node","text":"<p>Note</p> <p>Only the initial Dokku server will be properly configured for push deployment, and should be considered your git remote. Additional server nodes are for ensuring high-availability of the K3s etcd state. Ensure this server is properly backed up and restorable or deployments will not work.</p> <p>Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.</p> <p>Server nodes can also be added with the <code>scheduler-k3s:cluster-add</code> command by specifying <code>--role server</code>. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.</p> <pre><code>dokku scheduler-k3s:cluster-add  --role server ssh://root@server-1.example.com\n</code></pre> <p>Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the <code>--taint-scheduling</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com\n</code></pre> <p>If the server isn't in the <code>known_hosts</code> file, the connection will fail. This can be bypassed by setting the <code>--insecure-allow-unknown-hosts</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@server-1.example.com\n</code></pre> <p>By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the <code>--server-ip</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --server-ip 192.168.20.15 ssh://root@server-1.example.com\n</code></pre>"},{"location":"deployment/schedulers/k3s/#changing-the-network-interface","title":"Changing the network interface","text":"<p>When attaching an worker or server node, the K3s plugin will look at the IP associated with the <code>eth0</code> interface and use that to connect the new node to the cluster. To change this, set the <code>network-interface</code> property to the appropriate value.</p> <pre><code>dokku scheduler-k3s:set --global network-interface eth1\n</code></pre>"},{"location":"deployment/schedulers/k3s/#changing-deploy-timeouts","title":"Changing deploy timeouts","text":"<p>By default, app deploys will timeout after 300s. To customize this value, set the <code>deploy-timeout</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app deploy-timeout 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app deploy-timeout\n</code></pre> <p>The <code>deploy-timeout</code> property can also be set globally. The global default is <code>300s</code>.</p> <pre><code>dokku scheduler-k3s:set --global deploy-timeout 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global deploy-timeout\n</code></pre>"},{"location":"deployment/schedulers/k3s/#customizing-the-namespace","title":"Customizing the namespace","text":"<p>By default, app deploys will run against the <code>default</code> Kubernetes namespace. To customize this value, set the <code>namespace</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app namespace lollipop\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app namespace\n</code></pre> <p>The <code>namespace</code> property can also be set globally. The global default is <code>default</code>.</p> <pre><code>dokku scheduler-k3s:set --global namespace 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global namespace\n</code></pre>"},{"location":"deployment/schedulers/k3s/#enabling-rollback-on-failure","title":"Enabling rollback on failure","text":"<p>By default, app deploys do not rollback on failure. To enable this functionality, set the <code>rollback-on-failure</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app rollback-on-failure true\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app rollback-on-failure\n</code></pre> <p>The <code>rollback-on-failure</code> property can also be set globally. The global default is <code>false</code>.</p> <pre><code>dokku scheduler-k3s:set --global rollback-on-failure false\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global rollback-on-failure\n</code></pre>"},{"location":"deployment/schedulers/k3s/#using-image-pull-secrets","title":"Using image pull secrets","text":"<p>When authenticating against a registry via <code>registry:login</code>, the scheduler-k3s plugin will authenticate all servers in the cluster against the registry specified. If desired, an image pull secret can be used instead. To customize this value, set the <code>image-pull-secrets</code> property via <code>scheduler-k3s:set</code>:</p> <pre><code>dokku scheduler-k3s:set node-js-app image-pull-secrets lollipop\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app image-pull-secrets\n</code></pre> <p>The <code>image-pull-secrets</code> property can also be set globally. The global default is empty string, and k3s will use the local <code>registries.yaml</code> for any private registry pulls.</p> <pre><code>dokku scheduler-k3s:set --global image-pull-secrets 60s\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global image-pull-secrets\n</code></pre>"},{"location":"deployment/schedulers/k3s/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email-prod</code> or <code>letsencrypt-email-stag</code> property with the <code>--global</code> flag:</p> <pre><code># set the value for prod\ndokku scheduler-k3s:set --global letsencrypt-email-prod automated@dokku.sh\n\n# set the value for stag\ndokku scheduler-k3s:set --global letsencrypt-email-stag automated@dokku.sh\n</code></pre> <p>After enabling, all apps with an <code>https</code> port mapping that utilize the related letsencrypt server will be automatically updated to enable ssl. All http requests will then be redirected to https.</p>"},{"location":"deployment/schedulers/k3s/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. This can be changed on an app-level by setting the <code>letsencrypt-server</code> property with the <code>scheduler-k3s:set</code> command</p> <pre><code>dokku scheduler-k3s:set node-js-app letsencrypt-server staging\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler-k3s:set node-js-app letsencrypt-server\n</code></pre> <p>The <code>image-pull-secrets</code> property can also be set globally. The global default is <code>production</code>.</p> <pre><code>dokku scheduler-k3s:set --global letsencrypt-server staging\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler-k3s:set --global letsencrypt-server staging\n</code></pre> <p>After changing, all apps with an</p>"},{"location":"deployment/schedulers/k3s/#using-kubectl-remotely","title":"Using kubectl remotely","text":"<p>Warning</p> <p>Certain ports must be open for interacting with the remote kubernets api. Refer to the K3s networking documentation for the required open ports between servers prior to running the command.</p> <p>By default, Dokku assumes that all it controls all actions on the cluster, and thus does not expose the <code>kubectl</code> binary for administrators. To interact with kubectl, you will need to retrieve the <code>kubeconfig</code> for the cluster and configure your client to use that configuration.</p> <pre><code>dokku scheduler-k3s:show-kubeconfig\n</code></pre>"},{"location":"deployment/schedulers/k3s/#tutorial","title":"Tutorial","text":""},{"location":"deployment/schedulers/k3s/#single-node-cluster","title":"Single-node cluster","text":"<p>Initialize the cluster in single-node mode. This will start k3s on the Dokku node itself.</p> <pre><code># must be run as root\ndokku scheduler-k3s:initialize\n</code></pre> <p>The above command will initialize a cluster with the following configuration:</p> <ul> <li>etcd distributed backing store</li> <li>Wireguard as the networking flannel</li> <li>K3s automatic upgrader</li> <li>Longhorn distributed block storage</li> <li>Traefik configured to run on all nodes in the cluster</li> </ul> <p>Additionally, an internal token for authentication will be automatically generated. This token should be stored securely for later recovery, and can be displayed with via the <code>scheduler-k3s:report</code> command:</p> ShellOutput <pre><code>dokku scheduler-k3s:report --global\n</code></pre> <pre><code>=====&gt; --global scheduler-k3s information\n       scheduler k3s token: topsecret:server:token\n</code></pre> <p>Setup registry authentication. The K3s scheduler plugin will automatically pick up any newly configured registry backends and ensure nodes in the cluster have the credentials in place for pulling images from the cluster.</p> <pre><code># hub.docker.com\ndokku registry:login hub.docker.com $USERNAME $PASSWORD\n</code></pre> <p>To ensure images are pushed and pulled from the correct registry, set the correct <code>server</code> registry property. This can be set on a per-app basis, but we will set it globally here for this tutorial.</p> <pre><code>dokku registry:set --global server hub.docker.com\n</code></pre> <p>If using docker hub, you'll need to use a custom repository name. This can be set via a global template, allowing users access to the app name as the variable <code>AppName</code> as shown below.</p> <pre><code>dokku registry:set --global image-repo-template \"my-awesome-prefix/{{ .AppName }}\"\n</code></pre> <p>Additionally, apps should be configured to push images on the release phase via the <code>push-on-release</code> registry property.</p> <pre><code>dokku registry:set --global push-on-release true\n</code></pre> <p>As routing is handled by traefik managed on the k3s plugin, set the proxy plugin to <code>k3s</code> as well.</p> <pre><code>dokku proxy:set --global k3s\n</code></pre> <p>Ensure any other proxy implementations are disabled. Typically at least nginx will be running on the Dokku host and should be stopped if the host is used as load balancer.</p> <pre><code>dokku nginx:stop\n</code></pre> <p>Finally, set the scheduler to <code>k3s</code> so that app deploys will work on k3s.</p> <pre><code>dokku scheduler:set --global selected k3s\n</code></pre> <p>At this point, all app deploys will be performed against the k3s cluster.</p> <p>Note</p> <p>HTTP requests for apps can be performed against any node in the cluster. Without extra configuration, many other ports may also be available on the host. For security reasons, it may be desirable to place the k3s cluster behind one or more TCP load balancers while shutting off traffic to all cluster ports. Please consult your hosting provider for more information on how to provision a TCP load balancer and shut off all ports other than 22/80/443 access to the outside world.</p>"},{"location":"deployment/schedulers/k3s/#running-a-multi-cluster-node","title":"Running a multi-cluster node","text":"<p>Warning</p> <p>Certain ports must be open for cross-server communication. Refer to the K3s networking documentation for the required open ports between servers prior to running the command.</p> <p>For high-availability, it is recommended to add both worker and server nodes to the cluster. Dokku will default to starting the cluster with an embedded Etcd database backend, and is ready to add new worker or server nodes immediately.</p> <p>When attaching an worker or server node, the K3s plugin will look at the IP associated with the <code>eth0</code> interface and use that to connect the new node to the cluster. To change this, set the <code>network-interface</code> property to the appropriate value.</p> <pre><code>dokku scheduler-k3s:set --global network-interface eth1\n</code></pre> <p>Dokku will connect to remote servers via the <code>root</code> user with the <code>dokku</code> user's SSH key pair. Dokku servers may not have an ssh key pair by default, but they can be generated as needed via the <code>git:generate-deploy-key</code> command.</p> <pre><code>dokku git:generate-deploy-key\n</code></pre> <p>This key can then be displayed with the <code>git:public-key</code> command, and copied to the remote server's <code>/root/.ssh/authorized_keys</code> file.</p> <pre><code>dokku git:public-key\n</code></pre> <p>Multiple server nodes can be added with the <code>scheduler-k3s:cluster-add</code> command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.</p> <pre><code>dokku scheduler-k3s:cluster-add  --role server ssh://root@server-1.example.com\n</code></pre> <p>Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the <code>--taint-scheduling</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com\n</code></pre> <p>If the server isn't in the <code>known_hosts</code> file, the connection will fail. This can be bypassed by setting the <code>--insecure-allow-unknown-hosts</code> flag:</p> <pre><code>dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@worker-1.example.com\n</code></pre> <p>Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.</p> <p>Note</p> <p>Only the initial Dokku server will be properly configured for push deployment, and should be considered your git remote. Additional server nodes are for ensuring high-availability of the K3s etcd state. Ensure this server is properly backed up and restorable or deployments will not work.</p> <p>Worker nodes are used to run. To add an worker, run the <code>scheduler-k3s:cluster-add</code> with the <code>--role worker</code> flag. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.</p> <pre><code>dokku scheduler-k3s:cluster-add --role worker ssh://root@worker-1.example.com\n</code></pre>"},{"location":"deployment/schedulers/k3s/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented and unimplemented scheduler functionality for the <code>k3s</code> scheduler.</p>"},{"location":"deployment/schedulers/k3s/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the <code>scheduler-k3s</code> plugin.</p> <ul> <li><code>apps:clone</code></li> <li><code>apps:destroy</code></li> <li><code>apps:rename</code></li> <li><code>cron</code></li> <li><code>enter</code></li> <li><code>deploy</code></li> <li>healthchecks<ul> <li>Due to Kubernetes limitations, only a single healthcheck is supported for each of the <code>liveness</code>, <code>readiness</code>, and <code>startup</code> healthchecks</li> <li>Due to Kubernetes limitations, content checks are not supported</li> <li>Ports specified in the <code>app.json</code> are ignored in favor of the container port on the port mapping detected</li> </ul> </li> <li><code>logs</code></li> <li><code>ps:stop</code></li> <li><code>run</code><ul> <li>The <code>scheduler-post-run</code> trigger is not always triggered</li> </ul> </li> <li><code>run:detached</code></li> <li><code>run:list</code></li> </ul>"},{"location":"deployment/schedulers/k3s/#unimplemented-command-functionality","title":"Unimplemented command functionality","text":"<ul> <li><code>run:logs</code></li> <li><code>ps:inspect</code></li> </ul> <p>The following Dokku functionality is not implemented at this time.</p> <ul> <li><code>vector</code> log integration</li> <li>persistent storage</li> </ul>"},{"location":"deployment/schedulers/k3s/#logging-support","title":"Logging support","text":"<p>App logs for the <code>logs</code> command are fetched by Dokku from running containers via the <code>kubectl</code> cli. Persisting logs via Vector is not implemented at this time. Users may choose to configure the Vector Kubernetes integration directly by following this guide.</p>"},{"location":"deployment/schedulers/k3s/#supported-resource-management-properties","title":"Supported Resource Management Properties","text":"<p>The <code>k3s</code> scheduler supports a minimal list of resource limits and reservations. The following properties are supported:</p>"},{"location":"deployment/schedulers/k3s/#resource-limits","title":"Resource Limits","text":"<p>Note</p> <p>Cron tasks retrieve resource limits based on the computed cron task ID. If unspecified, the default will be 1 CPU and 512m RAM.</p> <ul> <li>cpu: is specified in number of CPUs a process can access.</li> <li>memory: should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).</li> </ul>"},{"location":"deployment/schedulers/k3s/#resource-reservations","title":"Resource Reservations","text":"<p>Note</p> <p>Cron tasks retrieve resource reservations based on the computed cron task ID. If unspecified, the default will be 1 CPU and 512m RAM.</p> <ul> <li>cpu: is specified in number of CPUs a process can access.</li> <li>memory: should be specified with a suffix of <code>b</code> (bytes), <code>k</code> (kilobytes), <code>m</code> (megabytes), <code>g</code> (gigabytes). Default unit is <code>m</code> (megabytes).</li> </ul>"},{"location":"deployment/schedulers/kubernetes/","title":"Kubernetes Scheduler","text":"<p>Warning</p> <p>This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.</p> <p>The Kubernetes Scheduler Plugin is available free as an external plugin. Please see the plugin's issue tracker for more information on the status of the plugin.</p> <p>For users that require additional functionality, please refer to the Sponsoring Documentation.</p>"},{"location":"deployment/schedulers/kubernetes/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented scheduler functionality for the <code>kubernetes</code> scheduler.</p>"},{"location":"deployment/schedulers/kubernetes/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with <code>kubectl</code> for running apps on a Kubernetes cluster. The following functionality is supported by the <code>scheduler-kubernetes</code> plugin.</p> <ul> <li><code>apps:destroy</code></li> <li><code>deploy</code>: partial, does not implement failed deploy log capture</li> <li><code>logs</code>: partial, does not implement failure logs</li> <li><code>ps:stop</code></li> </ul>"},{"location":"deployment/schedulers/kubernetes/#logging-support","title":"Logging support","text":"<p>App logs for the <code>logs</code> command are fetched from running pods via the <code>kubectl</code> cli. To persist logs across deployments, consider using Vector or a similar tool to ship logs to another service or a third-party platform.</p>"},{"location":"deployment/schedulers/nomad/","title":"Nomad Scheduler","text":"<p>Warning</p> <p>This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.</p> <p>The Nomad Scheduler Plugin is available free as an external plugin. Please see the plugin's issue tracker for more information on the status of the plugin.</p> <p>For users that require additional functionality, please refer to the Sponsoring Documentation.</p>"},{"location":"deployment/schedulers/nomad/#scheduler-interface","title":"Scheduler Interface","text":"<p>The following sections describe implemented scheduler functionality for the <code>nomad</code> scheduler.</p>"},{"location":"deployment/schedulers/nomad/#implemented-commands-and-triggers","title":"Implemented Commands and Triggers","text":"<p>This plugin implements various functionality through <code>plugn</code> triggers to integrate with the <code>nomad</code> cli for running apps on a Nomad cluster. The following functionality is supported by the <code>scheduler-nomad</code> plugin.</p> <ul> <li><code>apps:destroy</code></li> <li><code>deploy</code></li> <li><code>ps:stop</code></li> </ul>"},{"location":"deployment/schedulers/nomad/#logging-support","title":"Logging support","text":""},{"location":"deployment/schedulers/null/","title":"Null Scheduler","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>The <code>null</code> scheduler does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the network documentation for more information on the aforementioned use case.</p>"},{"location":"deployment/schedulers/null/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/null/#detection","title":"Detection","text":"<p>This scheduler is never auto-detected. The scheduler must  be specified via the <code>scheduler:set</code> command:</p> <pre><code>dokku scheduler:set node-js-app selected null\n</code></pre>"},{"location":"deployment/schedulers/scheduler-management/","title":"Scheduler Management","text":"<p>New</p> <p>Introduced in 0.26.0</p> <pre><code>scheduler:report [&lt;app&gt;] [&lt;flag&gt;]   # Displays a scheduler report for one or more apps\nscheduler:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;) # Set or clear a scheduler property for an app\n</code></pre> <p>Schedulers are a way of customizing how an app image is deployed, and can be used to interact with non-local systems such as Kubernetes and Nomad.</p>"},{"location":"deployment/schedulers/scheduler-management/#usage","title":"Usage","text":""},{"location":"deployment/schedulers/scheduler-management/#scheduler-selection","title":"Scheduler selection","text":"<p>Dokku supports the following built-in schedulers:</p> <ul> <li><code>scheduler-docker-local</code>: Schedules apps against the local docker socket and runs containers directly on the Dokku host. See the docker-local scheduler documentation for more information on how this scheduler functions.</li> <li><code>scheduler-null</code>: Does nothing during the scheduler phase. See the null scheduler documentation for more information on how this scheduler functions.</li> </ul>"},{"location":"deployment/schedulers/scheduler-management/#overriding-the-auto-selected-scheduler","title":"Overriding the auto-selected scheduler","text":"<p>If desired, the scheduler can be specified via the <code>scheduler:set</code> command by speifying a value for <code>selected</code>. The selected scheduler will always be used.</p> <pre><code>dokku scheduler:set node-js-app selected docker-local\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku scheduler:set node-js-app selected\n</code></pre> <p>The <code>selected</code> property can also be set globally. The global default is an empty string, and auto-detection will be performed when no value is set per-app or globally.</p> <pre><code>dokku scheduler:set --global selected docker-local\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku scheduler:set --global selected\n</code></pre>"},{"location":"deployment/schedulers/scheduler-management/#displaying-scheduler-reports-for-an-app","title":"Displaying scheduler reports for an app","text":"<p>You can get a report about the app's scheduler status using the <code>scheduler:report</code> command:</p> ShellOutput <pre><code>dokku scheduler:report\n</code></pre> <pre><code>=====&gt; node-js-app scheduler information\n       Scheduler computed selected:  herokuish\n       Scheduler global selected: herokuish\n       Scheduler selected: herokuish\n=====&gt; python-sample scheduler information\n       Scheduler computed selected: dockerfile\n       Scheduler global selected: herokuish\n       Scheduler selected: dockerfile\n=====&gt; ruby-sample scheduler information\n       Scheduler computed selected: herokuish\n       Scheduler global selected: herokuish\n       Scheduler selected:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku scheduler:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app scheduler information\n       Scheduler selected: herokuish\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku scheduler:report node-js-app --scheduler-selected\n</code></pre>"},{"location":"deployment/schedulers/scheduler-management/#implementing-a-scheduler","title":"Implementing a Scheduler","text":"<p>Custom plugins names must have the prefix <code>scheduler-</code> or scheduler overriding via <code>scheduler:set</code> may not function as expected.</p> <p>At this time, the following dokku commands are used to implement a complete scheduler.</p> <ul> <li><code>apps:destroy</code>: stops the app processes on the scheduler<ul> <li>triggers: post-delete, scheduler-register-retired, scheduler-retire</li> </ul> </li> <li><code>apps:rename</code>: handles app renaming<ul> <li>triggers: post-app-rename-setup</li> </ul> </li> <li><code>apps:clone</code>: handles app cloning<ul> <li>triggers: post-app-clone-setup</li> </ul> </li> <li><code>cron</code>: generates cron tasks for the app<ul> <li>triggers: cron-write</li> </ul> </li> <li><code>deploy</code>: deploys app proceses and checks the status of a deploy<ul> <li>triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed</li> </ul> </li> <li><code>enter</code>: enters a running container<ul> <li>triggers: scheduler-enter</li> </ul> </li> <li><code>logs</code>: fetches app logs<ul> <li>triggers: scheduler-logs</li> </ul> </li> <li><code>run</code>: starts one-off run containers (detached and non-detached) as well as listing run processes<ul> <li>triggers: scheduler-run, scheduler-run-list</li> </ul> </li> <li><code>run:list</code>: lists running containers<ul> <li>triggers: scheduler-run-list</li> </ul> </li> <li><code>run:logs</code>: fetches running container logs<ul> <li>triggers: scheduler-run-logs</li> </ul> </li> <li><code>ps:stop</code>: stops app processes<ul> <li>triggers: scheduler-stop</li> </ul> </li> <li><code>ps:inspect</code>: outputs inspect output for processes in an app<ul> <li>triggers: scheduler-inspect</li> </ul> </li> </ul> <p>Schedulers may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins. Additionally, a scheduler may implement other triggers in order handle any extra processes needed during a deploy.</p> <p>Schedulers can use any tools available on the system to build the docker image, and may even be used to interact with off-server systems. The only current requirement is that the scheduler must have access to the image built in the build phase. If this is not the case, the registry plugin can be used to push the image to a registry that the scheduler software can access.</p> <p>Deployment tasks are currently executed directly on the primary Dokku server.</p>"},{"location":"development/plugin-creation/","title":"Plugin creation","text":"<p>A plugin can be a simple implementation of triggers or can implement a command structure of its own. Dokku has no restrictions on the language in which a plugin is implemented; it only cares that the plugin implements the appropriate commands or triggers for the API. NOTE: any file that implements triggers or uses the command API must be executable.</p>"},{"location":"development/plugin-creation/#plugin-overview","title":"Plugin Overview","text":"<p>When creating custom plugins:</p> <ol> <li>Take a look at the plugins shipped with Dokku and hack away!</li> <li>Check out the list of triggers the plugin can implement</li> <li>Upload the plugin to GitHub with a repository name following the <code>dokku-&lt;name&gt;</code> convention (e.g. <code>dokku-mariadb</code>)</li> <li>Edit this page and add a link to the plugin</li> <li>Subscribe to the dokku development blog to be notified about API changes and releases</li> </ol>"},{"location":"development/plugin-creation/#compilable-plugins-golang-java-c-etc","title":"Compilable plugins (Golang, Java(?), C, etc.)","text":"<p>When developing a plugin, the <code>install</code> trigger must be implemented such that it outputs the built executable(s) using a directory structure that implements the plugin's desired command and/or triggers the API. See the smoke-test-plugin for an example.</p>"},{"location":"development/plugin-creation/#command-api","title":"Command API","text":"<p>There are 3 main integration points: <code>commands</code>, <code>subcommands/default</code>, and <code>subcommands/&lt;command-name&gt;</code>.</p>"},{"location":"development/plugin-creation/#commands","title":"<code>commands</code>","text":"<p>Primarily used to supply the plugin's usage/help output. (i.e. plugin help).</p>"},{"location":"development/plugin-creation/#subcommandsdefault","title":"<code>subcommands/default</code>","text":"<p>Implements the plugin's default command behavior. (i.e. <code>dokku plugin</code>).</p>"},{"location":"development/plugin-creation/#subcommandscommand-name","title":"<code>subcommands/&lt;command-name&gt;</code>","text":"<p>Implements the additional command interface and will translate to <code>dokku plugin:cmd</code> on the command line. (i.e. <code>dokku plugin:install</code>).</p>"},{"location":"development/plugin-creation/#plugin-building-tips","title":"Plugin Building Tips","text":""},{"location":"development/plugin-creation/#always-create-a-plugintoml","title":"Always create a <code>plugin.toml</code>","text":"<p>The <code>plugin.toml</code> file is used to describe the plugin in help output, and helps users understand the purpose of the plugin. This must have a description and a version. The version should be bumped at every plugin release.</p> <pre><code>[plugin]\ndescription = \"dokku example plugin\"\nversion = \"0.1.0\"\n[plugin.config]\n</code></pre>"},{"location":"development/plugin-creation/#files-should-be-executable","title":"Files should be executable","text":"<p>Commands, subcommands, triggers and source shell scripts should all be executable. On a Unix-like machine, the following command can be used to make them executable:</p> <pre><code>chmod +x path/to/file\n</code></pre> <p>Non-executable commands, subcommands, and triggers will be ignored.</p>"},{"location":"development/plugin-creation/#use-the-pipefail-bash-option","title":"Use the <code>pipefail</code> bash option","text":"<p>Consider whether to include the <code>set -eo pipefail</code> option. Look at the following example:</p> <pre><code>IMAGE=$(docker images | grep \"user/repo\" | awk '{print $3}')\nif [[ -z $IMAGE ]]; then\n  dokku_log_fail \"user/repo image not found... Did you run 'dokku plugin:install'?\"\nfi\n</code></pre> <p>If <code>user/repo</code> doesn't exist, Dokku exits just before the <code>awk</code> command and the <code>dokku_log_fail</code> message will never go to <code>STDOUT</code>. printed with echo. The <code>set -e</code> option should be used in this case.</p> <p>Here is the <code>help</code> entry for <code>set</code>:</p> <pre><code>help set\nOptions:\n  -e  Exit immediately if a command exits with a non-zero status.\n  -o option-name\n      pipefail     the return value of a pipeline is the status of\n                   the last command to exit with a non-zero status,\n                   or zero if no command exited with a non-zero status\n</code></pre>"},{"location":"development/plugin-creation/#support-trace-mode","title":"Support trace mode","text":"<p>Trace mode is useful for getting debugging output from plugins when the <code>--trace</code> flag is specified or <code>dokku trace:on</code> is triggered. This should be done at the top of each shell script:</p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\n</code></pre> <p>In the above example, the third line enables bash's debug mode, which prints command traces before executing command.</p>"},{"location":"development/plugin-creation/#verify-the-existence-of-dependencies","title":"Verify the existence of dependencies","text":"<p>If a plugin depends on a specific command-line tool, check whether that tool exists before utilizing it. Either <code>command -v</code> or <code>which</code> may be used to do so:</p> <pre><code># `command -v` example\nif ! command -v \"nginx\" &amp;&gt;/dev/null; then\n  dokku_log_fail \"Missing nginx, install it\"\nfi\n\n# `which` example\nif ! which nginx &amp;&gt;/dev/null; then\n  dokku_log_fail \"Missing nginx, install it\"\nfi\n</code></pre> <p>In cases where a dependency should be installed before the plugin can be used at all, use the <code>dependencies</code> plugin trigger to install the dependency.</p>"},{"location":"development/plugin-creation/#implement-a-help-command","title":"Implement a help command","text":"<p>For plugins which expose commands, implement a <code>help</code> command. This may be empty, but should contain a listing of all available commands.</p> <p>Commas - <code>,</code> - are used in the help output for columnizing output. Verify that the plugin conforms to the spec by running <code>dokku help --all</code> and manually verifying the output.</p> <p>See the sample plugin below for an example.</p>"},{"location":"development/plugin-creation/#namespace-commands","title":"Namespace commands","text":"<p>All commands should be namespaced. In cases where a core plugin is overriden, the plugin may utilize the a namespace in use by the core, but generally this should be avoided to reduce confusion as to where the command is implemented.</p>"},{"location":"development/plugin-creation/#implement-a-proper-catch-all-command","title":"Implement a proper catch-all command","text":"<p>As of 0.3.3, a catch-all should be implemented that exits with a <code>DOKKU_NOT_IMPLEMENTED_EXIT</code> code. This allows Dokku to output a <code>command not found</code> message.</p> <p>See the sample plugin below for an example.</p>"},{"location":"development/plugin-creation/#set-app-config-without-restarting","title":"Set app config without restarting","text":"<p>In the case that a plugin needs to set app configuration settings and a restart should be avoided (default Heroku-style behavior) these \"internal\" commands provide this functionality:</p> <pre><code>config_set --no-restart node-js-app KEY1=VALUE1 [KEY2=VALUE2 ...]\nconfig_unset --no-restart node-js-app KEY1 [KEY2 ...]\n</code></pre>"},{"location":"development/plugin-creation/#expose-functionality-in-a-functions-file","title":"Expose functionality in a <code>functions</code> file","text":"<p>To allow other plugins access to (some of) a plugin's functionality, functions can expose by including a <code>functions</code> file in the plugin for others to source. All functions in that file should be considered publicly accessible by other plugins.</p> <p>Any functions that must be kept private should reside in the plugin's <code>trigger/</code> or <code>commands/</code> directories. Other files may also be used to hide private functions; the official convention for hiding private functions is to place them an <code>internal-functions</code> file.</p>"},{"location":"development/plugin-creation/#use-helper-functions-to-fetch-app-images","title":"Use helper functions to fetch app images","text":"<p>New</p> <p>Introduced in 0.4.0</p> <p>Dokku allows image tagging and deployment of tagged images. This means hard-coding the <code>$IMAGE</code> as <code>dokku/$APP</code> is no longer sufficient.</p> <p>Plugins should use <code>get_running_image_tag()</code> and <code>get_app_image_name()</code> as sourced from <code>common/functions</code>. See the plugin triggers doc for examples.</p> <p>Info</p> <p>Note: This is only for plugins that are not <code>pre/post-build-*</code> plugins</p>"},{"location":"development/plugin-creation/#use-docker_bin-instead-of-docker-directly","title":"Use <code>$DOCKER_BIN</code> instead of <code>docker</code> directly","text":"<p>New</p> <p>Introduced in 0.17.5</p> <p>Certain systems may require a wrapper function around the <code>docker</code> binary for proper execution. Utilizing the <code>$DOCKER_BIN</code> environment variable when calling docker for those functions is preferred.</p> <pre><code># good\n\"$DOCKER_BIN\" container run -d $IMAGE /bin/bash -e -c \"$COMMAND\"\n\n# bad\ndocker run -d $IMAGE /bin/bash -e -c \"$COMMAND\"\n</code></pre>"},{"location":"development/plugin-creation/#include-labels-for-all-temporary-containers-and-images","title":"Include labels for all temporary containers and images","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>As of 0.5.0, labels are used to help cleanup intermediate containers with <code>dokku cleanup</code>. Plugins that create containers and images should add the correct labels to the <code>build</code>, <code>commit</code>, and <code>run</code> docker commands.</p> <p>Note that where possible, a label <code>com.dokku.app-name=$APP</code> - where <code>$APP</code> is the name of the app - should also be included. This enables <code>dokku cleanup APP</code> to cleanup the specific containers for a given app.</p> <pre><code># `docker build` example\n\"$DOCKER_BIN\" image build \"--label=com.dokku.app-name=${APP}\" $DOKKU_GLOBAL_BUILD_ARGS ...\n\n# `docker commit` example\n# Note that the arguments must be set as a local array\n# as arrays cannot be exported in shell\nlocal DOKKU_COMMIT_ARGS=(\"--change\" \"LABEL org.label-schema.schema-version=1.0\" \"--change\" \"LABEL org.label-schema.vendor=dokku\" \"--change\" \"LABEL $DOKKU_CONTAINER_LABEL=\")\n\"$DOCKER_BIN\" container commit --change \"LABEL com.dokku.app-name=$APP\" \"${DOKKU_COMMIT_ARGS[@]}\" ...\n\n# `docker run` example\n\"$DOCKER_BIN\" container run \"--label=com.dokku.app-name=${APP}\" $DOKKU_GLOBAL_RUN_ARGS ...\n</code></pre>"},{"location":"development/plugin-creation/#copy-files-from-the-built-image-using-copy_from_image","title":"Copy files from the built image using <code>copy_from_image</code>","text":"<p>Avoid copying files from running containers as these files may change over time. Instead copy files from the image built during the deploy process. This can be done via the <code>copy_from_image</code> helper function. This will correctly handle various corner cases in copying files from an image.</p> <pre><code>source \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nlocal TMP_FILE=$(mktemp \"/tmp/dokku-${DOKKU_PID}-${FUNCNAME[0]}.XXXXXX\")\ntrap \"rm -rf '$TMP_FILE' &gt;/dev/null\" RETURN INT TERM EXIT\n\nlocal IMAGE_TAG=\"$(get_running_image_tag \"$APP\")\"\nlocal IMAGE=$(get_deploying_app_image_name \"$APP\" \"$IMAGE_TAG\")\ncopy_from_image \"$IMAGE\" \"file-being-copied\" \"$TMP_FILE\" 2&gt;/dev/null\n</code></pre> <p>Files are copied from the <code>/app</code> directory - for images built via buildpacks - or <code>WORKDIR</code> - for images built via Dockerfile.</p>"},{"location":"development/plugin-creation/#avoid-calling-the-dokku-binary-directly","title":"Avoid calling the <code>dokku</code> binary directly","text":"<p>New</p> <p>Introduced in 0.6.0</p> <p>Plugins should not call the <code>dokku</code> binary directly from within plugins because clients using the <code>--app</code> argument are potentially broken when doing so.</p> <p>Plugins should instead source the <code>functions</code> file for a given plugin when attempting to call Dokku internal functions. In cases where plugin functions cannot be sourced (eg if a plugin is implemented in Golang), then call the relevant plugin triggers instead.</p>"},{"location":"development/plugin-creation/#sample-plugin","title":"Sample plugin","text":"<p>The below plugin is a dummy <code>dokku hello</code> plugin.</p> <p>Each plugin requires a <code>plugin.toml</code> descriptor file with the following required fields:</p> <pre><code>[plugin]\ndescription = \"dokku hello plugin\"\nversion = \"0.1.0\"\n[plugin.config]\n</code></pre> <p><code>hello/subcommands/default</code></p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\ncmd-hello-default() {\n  declare desc=\"prints Hello \\$APP\"\n  declare cmd=\"hello\"\n  [[ \"$1\" == \"$cmd\" ]] &amp;&amp; shift 1\n  # Support --app/$DOKKU_APP_NAME flag\n  # Use the following lines to reorder args into \"$cmd $DOKKU_APP_NAME $@\"\"\n  [[ -n $DOKKU_APP_NAME ]] &amp;&amp; set -- $DOKKU_APP_NAME $@\n  set -- $cmd $@\n  #\n  declare APP=\"$1\"\n\n  [[ -z \"$APP\" ]] &amp;&amp; dokku_log_fail \"Please specify an app to run the command on\"\n  verify_app_name \"$APP\"\n\n  echo \"Hello $APP\"\n}\n\ncmd-hello-default \"$@\"\n</code></pre> <p><code>hello/subcommands/world</code></p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\ncmd-hello-world() {\n  declare desc=\"prints Hello world\"\n  declare cmd=\"hello:world\"\n  [[ \"$1\" == \"$cmd\" ]] &amp;&amp; shift 1\n\n  echo \"Hello world\"\n}\n\ncmd-hello-world \"$@\"\n</code></pre> <p><code>hello/commands</code></p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail\n[[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncase \"$1\" in\n  help | hello:help)\n    help_content_func () {\n      declare desc=\"return help_content string\"\n      cat&lt;&lt;help_content\n    hello &lt;app&gt;, Says \"Hello &lt;app&gt;\"\n    hello:world, Says \"Hello world\"\nhelp_content\n    }\n\n    if [[ $1 = \"hello:help\" ]] ; then\n        echo -e 'Usage: dokku hello[:world] [&lt;app&gt;]'\n        echo ''\n        echo 'Say Hello World.'\n        echo ''\n        echo 'Example:'\n        echo ''\n        echo '$ dokku hello:world'\n        echo 'Hello world'\n        echo ''\n        echo 'Additional commands:'\n        help_content_func | sort | column -c2 -t -s,\n    else\n        help_content_func\n    fi\n    ;;\n\n  *)\n    exit $DOKKU_NOT_IMPLEMENTED_EXIT\n    ;;\n\nesac\n</code></pre>"},{"location":"development/plugin-triggers/","title":"Plugin triggers","text":"<p>Plugin triggers (formerly pluginhooks) are a good way to jack into existing Dokku infrastructure. You can use them to modify the output of various Dokku commands or override internal configuration.</p> <p>Plugin triggers are simply scripts that are executed by the system. You can use any language you want, so long as the script:</p> <ul> <li>Is executable</li> <li>Has the proper language requirements installed</li> </ul> <p>For instance, if you wanted to write a plugin trigger in PHP, you would need to have <code>php</code> installed and available on the CLI prior to plugin trigger invocation.</p> <p>The following is an example for the <code>nginx-hostname</code> plugin trigger. It reverses the hostname that is provided to nginx during deploys. If you created an executable file named <code>nginx-hostname</code> with the following code in your plugin trigger, it would be invoked by Dokku during the normal app deployment process:</p> <pre><code>#!/usr/bin/env bash\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; SUBDOMAIN=\"$2\"; VHOST=\"$3\"\n\nNEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`\necho \"$NEW_SUBDOMAIN.$VHOST\"\n</code></pre>"},{"location":"development/plugin-triggers/#available-plugin-triggers","title":"Available plugin triggers","text":"<p>There are a number of plugin-related triggers. These can be optionally implemented by plugins and allow integration into the standard Dokku setup/teardown process.</p> <p>The following plugin triggers describe those available to a Dokku installation. As well, there is an example for each trigger that you can use as templates for your own plugin development.</p> <p>Info</p> <p>The example plugin trigger code is not guaranteed to be implemented as in within dokku, and are merely simplified examples. Please look at the Dokku source for larger, more in-depth examples.</p>"},{"location":"development/plugin-triggers/#app-create","title":"<code>app-create</code>","text":"<ul> <li>Description: Creates an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-destroy","title":"<code>app-destroy</code>","text":"<ul> <li>Description: Destroys an app (with confirmation if force isn't specified)</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-exists","title":"<code>app-exists</code>","text":"<ul> <li>Description: Checks if an app exists</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-list","title":"<code>app-list</code>","text":"<ul> <li>Description: Lists all apps in available to the currently logged in user. Optionally disables filtering by user if the first argument is <code>false</code>.</li> <li>Invoked by:</li> <li>Arguments: <code>$FILTER</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-json-process-deploy-parallelism","title":"<code>app-json-process-deploy-parallelism</code>","text":"<ul> <li>Description: Decides the parallelism to use when deploying a given process type. The default is 1 process entry at a type.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-json-get-content","title":"<code>app-json-get-content</code>","text":"<ul> <li>Description: Outputs the contents of the app-json file, if any</li> <li>Invoked by: Deployment checks</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-maybe-create","title":"<code>app-maybe-create</code>","text":"<ul> <li>Description: Creates an app (gated by whether this is globally enabled or not)</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-restart","title":"<code>app-restart</code>","text":"<ul> <li>Description: Triggers an app restart</li> <li>Invoked by: <code>dokku config:clear</code>, <code>dokku config:set</code>, <code>dokku config:unset</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#app-urls","title":"<code>app-urls</code>","text":"<ul> <li>Description: Allows you to change the urls Dokku reports for an application. Will override any auto-detected urls.</li> <li>Invoked by: <code>dokku deploy</code>, <code>dokku url</code>, and <code>dokku urls</code></li> <li>Arguments: <code>$APP $URL_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Sets the domain to `internal.tld`\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; URL_TYPE=\"$2\"\ncase \"$URL_TYPE\" in\n  url)\n    echo \"https://internal.tld/${APP}/\"\n    ;;\n  urls)\n    echo \"https://internal.tld/${APP}/\"\n    echo \"http://internal.tld/${APP}/\"\n    ;;\nesac\n</code></pre>"},{"location":"development/plugin-triggers/#builder-build","title":"<code>builder-build</code>","text":"<ul> <li>Description: Triggers the artifact build process</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-create-dokku-image","title":"<code>builder-create-dokku-image</code>","text":"<ul> <li>Description: Allows modification of the configured dokku-image</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code> <code>$DOKKU_IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-detect","title":"<code>builder-detect</code>","text":"<ul> <li>Description: Allows overriding the auto-detected <code>herokuish</code> builder in favor of a custom one. Dockerfile gets lowest builder precedence.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; SOURCECODE_WORK_DIR=\"$2\"\n\nif [[ -f \"$SOURCECODE_WORK_DIR/project.toml\" ]]; then\n  echo -n \"pack\"\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#builder-dokku-image","title":"<code>builder-dokku-image</code>","text":"<ul> <li>Description: Allows modification of the used dokku-image.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code> <code>$DOKKU_IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-get-property","title":"<code>builder-get-property</code>","text":"<ul> <li>Description: Return the value for an app's builder property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-herokuish-allowed","title":"<code>builder-herokuish-allowed</code>","text":"<ul> <li>Description: Checks if herokuish is allowed to run on non-amd64 hosts</li> <li>Invoked by: unit tests</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-image-is-cnb","title":"<code>builder-image-is-cnb</code>","text":"<ul> <li>Description: Checks if an image is cnb-based</li> <li>Invoked by: unit tests</li> <li>Arguments: <code>$APP</code> <code>$IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-image-is-herokuish","title":"<code>builder-image-is-herokuish</code>","text":"<ul> <li>Description: Checks if an image is herokuish-based</li> <li>Invoked by: unit tests</li> <li>Arguments: <code>$APP</code> <code>$IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#builder-release","title":"<code>builder-release</code>","text":"<ul> <li>Description: Triggers the artifact release process</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$BUILDER_TYPE</code> <code>$APP</code> <code>$IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#buildpack-stack-name","title":"<code>buildpack-stack-name</code>","text":"<ul> <li>Description: Retrieves the configured buildpack stack for the pack and herokuish builders</li> <li>Invoked by: builder-herokuish and builder-pack</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#caddy-template-source","title":"<code>caddy-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the caddy compose config</li> <li>Invoked by: caddy-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#certs-exists","title":"<code>certs-exists</code>","text":"<ul> <li>Description: Echos <code>true</code> if certs exists for the app, <code>false</code> otherwise</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#certs-force","title":"<code>certs-force</code>","text":"<ul> <li>Description: Echos <code>true</code> if a cert should be simulated for the app, no output otherwise</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#check-deploy","title":"<code>check-deploy</code>","text":"<ul> <li>Description: Allows you to run checks on a deploy before Dokku allows the container to handle requests.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $CONTAINER_ID $PROC_TYPE $PORT $IP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Disables deploys of containers based on whether the\n# `DOKKU_DISABLE_DEPLOY` env var is set to `true` for an app\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_AVAILABLE_PATH/config/functions\"\n\nAPP=\"$1\"; CONTAINER_ID=\"$2\"; PROC_TYPE=\"$3\"; PORT=\"$4\" ; IP=\"$5\"\n\neval \"$(config_export app $APP)\"\nDOKKU_DISABLE_DEPLOY=\"${DOKKU_DISABLE_DEPLOY:-false}\"\n\nif [[ \"$DOKKU_DISABLE_DEPLOY\" = \"true\" ]]; then\n  echo -e \"\\033[31m\\033[1mDeploys disabled, sorry.\\033[0m\"\n  exit 1\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#checks-get-property","title":"<code>checks-get-property</code>","text":"<ul> <li>Description: Return the value for an app's checks property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#commands-help-and-commands-plugin_namehelp","title":"<code>commands help</code> and <code>commands &lt;PLUGIN_NAME&gt;:help</code>","text":"<ul> <li>Description: Your plugin should implement a <code>help</code> command in your <code>commands</code> file to take advantage of this plugin trigger. <code>commands help</code> is used by <code>dokku help</code> to aggregate all plugins abbreviated <code>help</code> output. Implementing  <code>&lt;PLUGIN_NAME&gt;:help</code> in your <code>commands</code> file gives users looking for help, a more detailed output. 'commands help' must be implemented inside the <code>commands</code> plugin file. It's recommended that <code>PLUGIN_NAME:help</code> be added to the commands file to ensure consistency among community plugins and give you a new avenue to share rich help content with your user.</li> <li>Invoked by: <code>dokku help</code> and <code>commands &lt;PLUGIN_NAME&gt;:help</code></li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Outputs help for the derp plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncase \"$1\" in\n  help | hello:help)\n    help_content_func () {\n      declare desc=\"return help_content string\"\n      cat&lt;&lt;help_content\n    hello &lt;app&gt;, Says \"Hello &lt;app&gt;\"\n    hello:world, Says \"Hello world\"\nhelp_content\n    }\n\n    if [[ $1 = \"hello:help\" ]] ; then\n        echo -e 'Usage: dokku hello[:world] [&lt;app&gt;]'\n        echo ''\n        echo 'Say Hello World.'\n        echo ''\n        echo 'Example:'\n        echo ''\n        echo '$ dokku hello:world'\n        echo 'Hello world'\n        echo ''\n        echo 'Additional commands:'\n        help_content_func | sort | column -c2 -t -s,\n    else\n        help_content_func\n    fi\n    ;;\n\n  *)\n    exit $DOKKU_NOT_IMPLEMENTED_EXIT\n    ;;\n\nesac\n</code></pre>"},{"location":"development/plugin-triggers/#config-export","title":"<code>config-export</code>","text":"<ul> <li>Description: Returns the environment variables in a specified format</li> <li>Invoked by: app-json plugin</li> <li>Arguments: <code>$APP $GLOBAL $MERGED $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#config-get","title":"<code>config-get</code>","text":"<ul> <li>Description: Fetches the app config value for a key</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#config-get-global","title":"<code>config-get-global</code>","text":"<ul> <li>Description: Fetches the global config value for a key</li> <li>Invoked by:</li> <li>Arguments: <code>$KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#core-post-deploy","title":"<code>core-post-deploy</code>","text":"<p>Info</p> <p>To avoid issues with community plugins, this plugin trigger should be used only for core plugins. Please avoid using this trigger in your own plugins.</p> <ul> <li>Description: Allows running of commands after an app's processes have been scaled up, but before old containers are torn down. Dokku core currently uses this to switch traffic on nginx.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $INTERNAL_PORT $INTERNAL_IP_ADDRESS $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Notify an external service that a successful deploy has occurred.\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncurl \"http://httpstat.us/200\"\n</code></pre>"},{"location":"development/plugin-triggers/#core-post-extract","title":"<code>core-post-extract</code>","text":"<p>Info</p> <p>To avoid issues with community plugins, this plugin trigger should be used only for core plugins. Please avoid using this trigger in your own plugins.</p> <ul> <li>Description: Allows you to modify the contents of an app after it has been extracted from git but before the image source type is detected.</li> <li>Invoked by: The <code>receive-app</code> plugin trigger</li> <li>Arguments: <code>$APP</code> <code>$TMP_WORK_DIR</code> <code>$REV</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Adds a clock process to an app's Procfile\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\nTMP_WORK_DIR=\"$2\"\nREV=\"$3\" # optional, may not be sent for tar-based builds\n\npushd \"$TMP_WORK_DIR\" &gt;/dev/null\ntouch Procfile\necho \"clock: some-command\" &gt;&gt; Procfile\npopd &amp;&gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#cron-get-property","title":"<code>cron-get-property</code>","text":"<ul> <li>Description: Return the value for an app's cron property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#cron-entries","title":"<code>cron-entries</code>","text":"<ul> <li>Description: Allows injecting cron entries into the written out scheduled cron task list. Each entry is newline delimited, and individual entries come in the form <code>$SCHEDULE;$FULL_COMMAND;$ARBITRARY_DATA</code>. Individual implementations of cron writing can decide whether and how to include these cron entries. The <code>ARBITRARY_DATA</code> includes the log file path for the basic <code>docker-local</code> cron implementation.</li> <li>Invoked by:</li> <li>Arguments: <code>$DOKKU_SCHEDULER</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nDOKKU_SCHEDULER=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#cron-write","title":"<code>cron-write</code>","text":"<ul> <li>Description: Force triggers writing out cron entries</li> <li>Invoked by:</li> <li>Arguments:</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#dependencies","title":"<code>dependencies</code>","text":"<ul> <li>Description: Used to install system-level dependencies.</li> <li>Invoked by: <code>dokku plugin:install-dependencies</code></li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Installs nginx for the current plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nexport DEBIAN_FRONTEND=noninteractive\n\ncase \"$DOKKU_DISTRO\" in\n  debian|raspbian|ubuntu)\n    apt-get -qq -y --no-install-recommends install nginx\n    ;;\n  *)\n    echo \"Installation on $DOKKU_DISTRO not supported\" 1&gt;&amp;2\n    ;;\nesac\n</code></pre>"},{"location":"development/plugin-triggers/#deploy","title":"<code>deploy</code>","text":"<ul> <li>Description: Triggers a deploy for the given app. Can override the image tag to deploy, as well as specify a single process type to deploy.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP [$IMAGE_TAG] [$PROC_TYPE]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\" IMAGE_TAG=\"$2\" PROC_TYPE=\"$3\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#deployed-app-image-repo","title":"<code>deployed-app-image-repo</code>","text":"<ul> <li>Description: Used to manage the full repo of the image being deployed. Useful for deploying from an external registry where the repository name is not <code>dokku/$APP</code></li> <li>Invoked by: <code>internal function dokku_deploy_cmd() (deploy phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"\n# change the repo from dokku/APP to dokkupaas/APP\necho \"dokkupaas/$APP\"\n</code></pre>"},{"location":"development/plugin-triggers/#deployed-app-image-tag","title":"<code>deployed-app-image-tag</code>","text":"<ul> <li>Description: Used to manage the tag of the image being deployed. Useful for deploying a specific version of an image, or when deploying from an external registry</li> <li>Invoked by: <code>internal function dokku_deploy_cmd() (deploy phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# customize the tag version\necho 'not-latest'\n</code></pre>"},{"location":"development/plugin-triggers/#deployed-app-repository","title":"<code>deployed-app-repository</code>","text":"<ul> <li>Description: Used to manage the remote repository of the image being deployed.</li> <li>Invoked by: <code>internal function dokku_deploy_cmd() (deploy phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\necho 'derp.dkr.ecr.us-east-1.amazonaws.com'\n</code></pre>"},{"location":"development/plugin-triggers/#deploy-source-set","title":"<code>deploy-source-set</code>","text":"<ul> <li>Description: Used to set metadata about how the app is being deployed</li> <li>Invoked by: <code>git:from-archive</code>, <code>git:from-image</code>, <code>git:load-image</code>, <code>git:sync</code>, and all git push commands</li> <li>Arguments: <code>$APP $SOURCE_TYPE $METADATA</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-build","title":"<code>docker-args-build</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>docker-args-process-build</code> instead</p> <ul> <li>Description:</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Sets a docker build-arg called CACHEBUST which can be used\n# to bust cache at any arbitrary point in a Dockerfile build\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nSTDIN=$(cat)\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$2\"\noutput=\"\"\n\nif [[ \"$IMAGE_SOURCE_TYPE\" == \"dockerfile\" ]]; then\n  output=\" --build-arg CACHEBUST=$(date +%s)\"\nfi\necho -n \"$STDIN$output\"\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-deploy","title":"<code>docker-args-deploy</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>docker-args-process-deploy</code> instead</p> <ul> <li>Description:</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG [$PROC_TYPE $CONTAINER_INDEX]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-process-build","title":"<code>docker-args-process-build</code>","text":"<ul> <li>Description: <code>$PROC_TYPE</code> may be set to magic <code>_all_</code> process type to signify global docker deploy options.</li> <li>Invoked by: <code>dokku ps:rebuild</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-process-deploy","title":"<code>docker-args-process-deploy</code>","text":"<ul> <li>Description: <code>$PROC_TYPE</code> may be set to magic <code>_all_</code> process type to signify global docker deploy options.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE $IMAGE_TAG [$PROC_TYPE $CONTAINER_INDEX]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; $IMAGE_SOURCE_TYPE=\"$2\" IMAGE_TAG=\"$3\"; PROC_TYPE=\"$4\"; CONTAINER_INDEX=\"$5\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-process-run","title":"<code>docker-args-process-run</code>","text":"<ul> <li>Description: <code>$PROC_TYPE</code> may be set to magic <code>_all_</code> process type to signify global docker run options.</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$3\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#docker-args-run","title":"<code>docker-args-run</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>docker-args-process-run</code> instead</p> <ul> <li>Description:</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-add","title":"<code>domains-add</code>","text":"<ul> <li>Description: Adds a domain to an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$DOMAIN</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-disable","title":"<code>domains-disable</code>","text":"<ul> <li>Description: Disables domains for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$RESTART_APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-enable","title":"<code>domains-enable</code>","text":"<ul> <li>Description: Enables domains for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$RESTART_APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-list","title":"<code>domains-list</code>","text":"<ul> <li>Description: Lists all domains for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-urls","title":"<code>domains-urls</code>","text":"<ul> <li>Description: Gets an app's url(s)</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $URL_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#domains-vhost-enabled","title":"<code>domains-vhost-enabled</code>","text":"<ul> <li>Description: Checks if a virtual hosts are enabled for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-deploy-branch","title":"<code>git-deploy-branch</code>","text":"<ul> <li>Description: Outputs the deploy branch for an app, inherited or not</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-get-property","title":"<code>git-get-property</code>","text":"<ul> <li>Description: Return the value for an app's git property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-from-archive","title":"<code>git-from-archive</code>","text":"<ul> <li>Description: Updates an app's git repository from an archive and then triggers a build</li> <li>Invoked by: <code>git:from-archive</code></li> <li>Arguments: <code>$APP $ARCHIVE_URL $ARCHIVE_TYPE $USER_NAME $USER_EMAIL</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-from-directory","title":"<code>git-from-directory</code>","text":"<ul> <li>Description: Updates an app's git repository from a source directory and then triggers a build</li> <li>Invoked by: <code>git:from-image</code> and <code>git:from-archive</code></li> <li>Arguments: <code>$APP $SOURCECODE_WORK_DIR $USER_NAME $USER_EMAIL</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-from-image","title":"<code>git-from-image</code>","text":"<ul> <li>Description: Updates an app's git repository from a docker image and then triggers a build as necessary</li> <li>Invoked by: <code>git:from-image</code></li> <li>Arguments: <code>$APP $DOCKER_IMAGE $BUILD_DIR $USER_NAME $USER_EMAIL</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-has-code","title":"<code>git-has-code</code>","text":"<ul> <li>Description: Checks to see if there is code at the specified branch</li> <li>Arguments: <code>$APP $BRANCH_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-post-pull","title":"<code>git-post-pull</code>","text":"<ul> <li>Description:</li> <li>Invoked by: <code>dokku git-upload-pack</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#git-pre-pull","title":"<code>git-pre-pull</code>","text":"<ul> <li>Description:</li> <li>Invoked by: <code>dokku git-upload-pack</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre> <p>Warning</p> <p>The <code>git-pre-pull</code> trigger should not be used for authentication since it does not get called for commands that use <code>git-upload-archive</code> such as <code>git archive</code>. Instead, use the <code>user-auth</code> trigger.</p>"},{"location":"development/plugin-triggers/#git-revision","title":"<code>git-revision</code>","text":"<ul> <li>Description: Allows you to fetch the current git revision for a given application</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#install","title":"<code>install</code>","text":"<ul> <li>Description: Used to setup any files/configuration for a plugin.</li> <li>Invoked by: <code>dokku plugin:install</code>.</li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Sets the hostname of the Dokku server\n# based on the output of `hostname -f`\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nif [[ ! -f  \"$DOKKU_ROOT/VHOST\" ]]; then\n  hostname -f &gt; $DOKKU_ROOT/VHOST\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#haproxy-template-source","title":"<code>haproxy-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the haproxy compose config</li> <li>Invoked by: haproxy-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#logs-get-property","title":"<code>logs-get-property</code>","text":"<ul> <li>Description: Return the value for an app's log property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-build-config","title":"<code>network-build-config</code>","text":"<ul> <li>Description: Rebuilds network configuration</li> <li>Invoked by: <code>internally triggered by proxy-build-config within proxy implementations</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-clear-config","title":"<code>network-clear-config</code>","text":"<ul> <li>Description: Clears network configuration</li> <li>Invoked by: <code>internally triggered within proxy implementations</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-config-exists","title":"<code>network-config-exists</code>","text":"<ul> <li>Description: Returns whether the network configuration for a given app exists</li> <li>Invoked by: <code>internally triggered by core-post-deploy within proxy implementations</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-ipaddr","title":"<code>network-get-ipaddr</code>","text":"<ul> <li>Description: Return the ipaddr for a given app container</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROC_TYPE $CONTAINER_ID</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-listeners","title":"<code>network-get-listeners</code>","text":"<ul> <li>Description: Return the listeners (host:port combinations) for a given app container</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-property","title":"<code>network-get-property</code>","text":"<ul> <li>Description: Return the value for an app's network property</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-get-static-listeners","title":"<code>network-get-static-listeners</code>","text":"<ul> <li>Description: Return the network value for an app's property</li> <li>Invoked by: <code>internally triggered by proxy-build-config</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-write-ipaddr","title":"<code>network-write-ipaddr</code>","text":"<ul> <li>Description: Write the ipaddr for a given app index</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROC_TYPE $CONTAINER_INDEX $IP_ADDRESS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#network-write-port","title":"<code>network-write-port</code>","text":"<ul> <li>Description: Write the port for a given app index</li> <li>Invoked by: <code>internally triggered by a deploy</code></li> <li>Arguments: <code>$APP $PROC_TYPE $CONTAINER_INDEX $PORT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#nginx-app-template-source","title":"<code>nginx-app-template-source</code>","text":"<ul> <li>Description: Return the path to a <code>sigil</code> template that should be used to generate a given nginx configuration file.</li> <li>Invoked by: <code>nginx-vhosts#build-config</code></li> <li>Arguments: <code>$APP $TEMPLATE_TYPE</code><ul> <li>The <code>TEMPLATE_TYPE</code> argument can be one of: <code>[app-config, hsts-config, validate-config]</code></li> </ul> </li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\"\nTEMPLATE_TYPE=\"$2\"\ncase \"$TEMPLATE_TYPE\" in\n  app-config)\n    echo \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/app.conf.sigil\";;\n  hsts-config)\n    echo \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/hsts.conf.sigil\";;\n  validate-config)\n    echo \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/validate.conf.sigil\";;\n  *)\n    dokku_log_fail \"Invalid template type: ${TEMPLATE_TYPE}\"\nesac\n</code></pre> <p>The default templates are viewable here: plugins/nginx-vhosts/templates/</p>"},{"location":"development/plugin-triggers/#nginx-dokku-template-source","title":"<code>nginx-dokku-template-source</code>","text":"<ul> <li>Description: Return the path to a <code>sigil</code> template that should be used to generate the <code>dokku.conf</code> nginx configuration file.</li> <li>Invoked by: <code>nginx-vhosts#install</code></li> <li>Arguments: None, however the <code>sigil</code> template can make use of the following variables: <code>$.DOKKU_ROOT $.NGINX_ROOT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\necho \"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" &amp;&amp; pwd)/dokku.conf.sigil\"\n</code></pre> <p>The default template is viewable here: plugins/nginx-vhosts/templates/dokku.conf.sigil</p>"},{"location":"development/plugin-triggers/#nginx-hostname","title":"<code>nginx-hostname</code>","text":"<ul> <li>Description: Allows you to customize the hostname for a given app</li> <li>Invoked by: <code>dokku domains:setup</code></li> <li>Arguments: <code>$APP $SUBDOMAIN $VHOST</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Reverses the hostname for the app\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; SUBDOMAIN=\"$2\"; VHOST=\"$3\"\n\nNEW_SUBDOMAIN=`echo $SUBDOMAIN | rev`\necho \"$NEW_SUBDOMAIN.$VHOST\"\n</code></pre>"},{"location":"development/plugin-triggers/#nginx-pre-reload","title":"<code>nginx-pre-reload</code>","text":"<p>Warning</p> <p>The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run <code>plugn trigger network-get-listeners APP</code> within any implementation of <code>nginx-pre-reload</code> in order to retrieve all application listeners.</p> <ul> <li>Description: Run before nginx reloads hosts</li> <li>Invoked by: <code>dokku proxy:build-config</code></li> <li>Arguments: <code>$APP $INTERNAL_PORT $INTERNAL_IP_ADDRESS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs a check against all nginx conf files\n# to ensure they are valid\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nnginx -t\n</code></pre>"},{"location":"development/plugin-triggers/#openresty-template-source","title":"<code>openresty-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the openresty compose config</li> <li>Invoked by: openresty-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-clear","title":"<code>ports-clear</code>","text":"<ul> <li>Description: Clears the ports for a given app without triggering further restarts or rebuilds</li> <li>Invoked by: internally</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-configure","title":"<code>ports-configure</code>","text":"<ul> <li>Description: Configures the initial proxy ports</li> <li>Invoked by: <code>internally triggered by proxy plugins</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-get","title":"<code>ports-get</code>","text":"<ul> <li>Description: Returns a list of port mappings, newline delimited</li> <li>Invoked by: Various networking plugins</li> <li>Arguments: <code>$APP $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-get-available","title":"<code>ports-get-available</code>","text":"<ul> <li>Description: Prints out an available port greater than 1024</li> <li>Invoked by: Various networking plugins</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-get-property","title":"<code>ports-get-property</code>","text":"<ul> <li>Description: Return the value for an app's ports property</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $KEY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROPERTY=\"$2\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ports-set-detected","title":"<code>ports-set-detected</code>","text":"<ul> <li>Description: Allows builders to specify detected port mappings for a given app</li> <li>Invoked by: Builder plugins</li> <li>Arguments: <code>$APP [$PORT_MAPPING...]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-clone","title":"<code>post-app-clone</code>","text":"<ul> <li>Description: Allows you to run commands after an app was cloned.</li> <li>Invoked by: <code>dokku apps:clone</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-clone-setup","title":"<code>post-app-clone-setup</code>","text":"<ul> <li>Description: Allows you to run commands after an app is setup, and before it is rebuild. This is useful for cleaning up tasks, or ensuring configuration from an old app is copied to the new app</li> <li>Invoked by: <code>dokku apps:clone</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-rename","title":"<code>post-app-rename</code>","text":"<ul> <li>Description: Allows you to run commands after an app was renamed.</li> <li>Invoked by: <code>dokku apps:rename</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-app-rename-setup","title":"<code>post-app-rename-setup</code>","text":"<ul> <li>Description: Allows you to run commands after an app is setup, and before it is rebuild. This is useful for cleaning up tasks, or ensuring configuration from an old app is copied to the new app</li> <li>Invoked by: <code>dokku apps:rename</code></li> <li>Arguments: <code>$OLD_APP_NAME $NEW_APP_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build","title":"<code>post-build</code>","text":"<ul> <li>Description: Allows you to run commands after the build image is create for a given app.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$BUILDER_TYPE $APP $SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-buildpack","title":"<code>post-build-buildpack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using buildpacks.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-dockerfile","title":"<code>post-build-dockerfile</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using a dockerfile.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-lambda","title":"<code>post-build-lambda</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using lambda.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-build-pack","title":"<code>post-build-pack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>post-build</code> instead</p> <ul> <li>Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using pack.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-certs-remove","title":"<code>post-certs-remove</code>","text":"<ul> <li>Description: Allows you to run commands after a cert is removed</li> <li>Invoked by: <code>dokku certs:remove</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-certs-update","title":"<code>post-certs-update</code>","text":"<ul> <li>Description: Allows you to run commands after a cert is added/updated</li> <li>Invoked by: <code>dokku certs:add</code>, <code>dokku certs:update</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-config-update","title":"<code>post-config-update</code>","text":"<ul> <li>Description: Allows you to get notified when one or more configs is added or removed. Action can be <code>set</code> or <code>unset</code>.</li> <li>Invoked by: <code>dokku config:set</code>, <code>dokku config:unset</code></li> <li>Arguments: <code>$APP</code> <code>set|unset</code> <code>key1=VALUE1 key2=VALUE2</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-container-create","title":"<code>post-container-create</code>","text":"<ul> <li>Description: This trigger should be used to do stuff to containers after they are created but before they are started. They are explicitely for commands that may involve network traffic, and not for commands that are self-contained, such as chown or tar.</li> <li>Invoked by: <code>dokku run</code>, <code>dokku ps:rebuild</code>, <code>dokku deploy</code></li> <li>Arguments: \"app|service\" \"$CONTAINER_ID\" \"$APP|$SERVICE\" \"$PHASE\"</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-create","title":"<code>post-create</code>","text":"<ul> <li>Description: Can be used to run commands after an app is created.</li> <li>Invoked by: <code>dokku apps:create</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs a command to ensure that an app\n# has a postgres database when it is starting\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\nPOSTGRES=\"$1\"\n\ndokku postgres:create $POSTGRES\ndokku postgres:link $POSTGRES $APP\n</code></pre>"},{"location":"development/plugin-triggers/#post-delete","title":"<code>post-delete</code>","text":"<ul> <li>Description: Can be used to run commands after an app is deleted.</li> <li>Invoked by: <code>dokku apps:destroy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs a command to ensure that an app's\n# postgres installation is removed\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\n\ndokku postgres:destroy $APP\n</code></pre>"},{"location":"development/plugin-triggers/#post-deploy","title":"<code>post-deploy</code>","text":"<p>Info</p> <p>Please see core-post-deploy if contributing a core plugin with the <code>post-deploy</code> hook.</p> <ul> <li>Description: Allows running of commands after an app's processes have been scaled up, but before old containers are torn down. Dokku calls this after <code>core-post-deploy</code>. Deployment Tasks are also invoked by this plugin trigger.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $INTERNAL_PORT $INTERNAL_IP_ADDRESS $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Notify an external service that a successful deploy has occurred.\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncurl \"http://httpstat.us/200\"\n</code></pre>"},{"location":"development/plugin-triggers/#post-domains-update","title":"<code>post-domains-update</code>","text":"<ul> <li>Description: Allows you to run commands once the domain for an app has been updated. It also sends in the command that has been used. This can be \"add\", \"clear\" or \"remove\". The third argument will be the optional list of domains</li> <li>Invoked by: <code>dokku domains:add</code>, <code>dokku domains:clear</code>, <code>dokku domains:remove</code>, <code>dokku domains:set</code></li> <li>Arguments: <code>$APP</code> <code>action name</code> <code>domains</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Reloads haproxy for our imaginary haproxy plugin\n# that replaces the nginx-vhosts plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nsudo service haproxy reload\n</code></pre>"},{"location":"development/plugin-triggers/#post-extract","title":"<code>post-extract</code>","text":"<ul> <li>Description: Allows you to modify the contents of an app after it has been extracted from git but before the image source type is detected.</li> <li>Invoked by: The <code>receive-app</code> plugin trigger</li> <li>Arguments: <code>$APP</code> <code>$TMP_WORK_DIR</code> <code>$REV</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Adds a clock process to an app's Procfile\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\nTMP_WORK_DIR=\"$2\"\nREV=\"$3\" # optional, may not be sent for tar-based builds\n\npushd \"$TMP_WORK_DIR\" &gt;/dev/null\ntouch Procfile\necho \"clock: some-command\" &gt;&gt; Procfile\npopd &amp;&gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#post-proxy-ports-update","title":"<code>post-proxy-ports-update</code>","text":"<ul> <li>Description: Allows you to run commands once the port mappings for an app have been updated. It also sends the invoking command. This can be \"add\", \"clear\" or \"remove\".</li> <li>Invoked by: <code>dokku ports:add</code>, <code>dokku ports:clear</code>, <code>dokku ports:remove</code></li> <li>Arguments: <code>$APP</code> <code>action name</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Rebuilds haproxy config for our imaginary haproxy plugin\n# that replaces the nginx-vhosts plugin\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nsource \"$PLUGIN_AVAILABLE_PATH/haproxy/functions\"\nAPP=\"$1\"\n\nhaproxy-build-config \"$APP\"\n</code></pre>"},{"location":"development/plugin-triggers/#post-registry-login","title":"<code>post-registry-login</code>","text":"<ul> <li>Description: Allows running a command after the a registry has been logged into</li> <li>Invoked by: <code>dokku registry:login</code></li> <li>Arguments: <code>$DOCKER_REGISTRY_SERVER $DOCKER_REGISTRY_USER</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\n# the DOCKER_REGISTRY_PASS env var is also set\necho \"$DOCKER_REGISTRY_PASS\"\n</code></pre>"},{"location":"development/plugin-triggers/#post-release-builder","title":"<code>post-release-builder</code>","text":"<p>Warning</p> <p>Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.</p> <ul> <li>Description: Invokes a command after the build process is complete.</li> <li>Invoked by: builder plugins</li> <li>Arguments: <code>$BUILDER_TYPE $APP $IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nBUILDER_TYPE=\"$1\"; APP=\"$2\"; IMAGE=$3\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-stack-set-todo","title":"<code>post-stack-set</code> TODO","text":"<ul> <li>Description: Allows you to run commands after changing the stack</li> <li>Invoked by: buildpacks plugin</li> <li>Arguments: <code>$APP</code> <code>$VALUE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#post-stop","title":"<code>post-stop</code>","text":"<ul> <li>Description: Can be used to run commands after an app is manually stopped</li> <li>Invoked by: <code>dokku ps:stop</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Marks an app as manually stopped\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\n\ndokku config:set --no-restart $APP MANUALLY_STOPPED=1\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build","title":"<code>pre-build</code>","text":"<ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$BUILDER_TYPE $APP $SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-buildpack","title":"<code>pre-build-buildpack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using buildpacks.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-dockerfile","title":"<code>pre-build-dockerfile</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using a dockerfile.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-lambda","title":"<code>pre-build-lambda</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using lambda.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-build-pack","title":"<code>pre-build-pack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-build</code> instead</p> <ul> <li>Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using pack.</li> <li>Invoked by: <code>internal function dokku_build() (build phase)</code></li> <li>Arguments: <code>$APP</code> <code>$SOURCECODE_WORK_DIR</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-delete","title":"<code>pre-delete</code>","text":"<ul> <li>Description: Can be used to run commands before an app is deleted.</li> <li>Invoked by: <code>dokku apps:destroy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Clears out the gulp asset build cache for apps\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\n\nAPP=\"$1\"; GULP_CACHE_DIR=\"$DOKKU_ROOT/$APP/gulp\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\nif [[ -d $GULP_CACHE_DIR ]]; then\n  docker run \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" --rm -v \"$GULP_CACHE_DIR:/gulp\" \"$IMAGE\" find /gulp -depth -mindepth 1 -maxdepth 1 -exec rm -Rf {} \\; || true\nfi\n</code></pre>"},{"location":"development/plugin-triggers/#pre-deploy","title":"<code>pre-deploy</code>","text":"<ul> <li>Description: Allows the running of code before the app's processes are scaled up and after the docker images are prepared.</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Runs gulp in our container\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\ndokku_log_info1 \"Running gulp\"\nCID=$(docker run \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" -d $IMAGE /bin/bash -c \"cd /app &amp;&amp; gulp default\")\ntest $(docker wait $CID) -eq 0\nDOCKER_COMMIT_LABEL_ARGS=(\"--change\" \"LABEL org.label-schema.schema-version=1.0\" \"--change\" \"LABEL org.label-schema.vendor=dokku\" \"--change\" \"LABEL com.dokku.app-name=$APP\")\ndocker commit \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" $CID $IMAGE &gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#pre-disable-vhost","title":"<code>pre-disable-vhost</code>","text":"<ul> <li>Description: Allows you to run commands before the VHOST feature is disabled</li> <li>Invoked by: <code>dokku domains:disable</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-enable-vhost","title":"<code>pre-enable-vhost</code>","text":"<ul> <li>Description: Allows you to run commands before the VHOST feature is enabled</li> <li>Invoked by: <code>dokku domains:enable</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-receive-app","title":"<code>pre-receive-app</code>","text":"<ul> <li>Description: Allows you to customize the contents of an app directory before they are processed for deployment. The <code>IMAGE_SOURCE_TYPE</code> can be any of <code>[herokuish, dockerfile]</code></li> <li>Invoked by: <code>dokku git-hook</code>, <code>dokku tar-build-locked</code></li> <li>Arguments: <code>$APP $IMAGE_SOURCE_TYPE $TMP_WORK_DIR $REV</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Adds a file called `dokku-is-awesome` to the repository\n# the contents will be the app name\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; IMAGE_SOURCE_TYPE=\"$2\"; TMP_WORK_DIR=\"$3\"; REV=\"$4\"\n\necho \"$APP\" &gt; \"$TMP_WORK_DIR/dokku-is-awesome\"\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-builder","title":"<code>pre-release-builder</code>","text":"<ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$BUILDER_TYPE $APP $IMAGE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nBUILDER_TYPE=\"$1\"; APP=\"$2\"; IMAGE_TAG=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-buildpack","title":"<code>pre-release-buildpack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using buildpacks.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Installs the graphicsmagick package into the container\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\ndokku_log_info1 \"Installing GraphicsMagick...\"\n\nCMD=\"cat &gt; gm &amp;&amp; \\\n  dpkg -s graphicsmagick &amp;&gt;/dev/null || \\\n  (apt-get update -qq &amp;&amp; apt-get -qq -y --no-install-recommends install graphicsmagick &amp;&amp; apt-get clean)\"\n\nCID=$(docker run $DOKKU_GLOBAL_RUN_ARGS -i -a stdin $IMAGE /bin/bash -c \"$CMD\")\ntest $(docker wait $CID) -eq 0\nDOCKER_COMMIT_LABEL_ARGS=(\"--change\" \"LABEL org.label-schema.schema-version=1.0\" \"--change\" \"LABEL org.label-schema.vendor=dokku\" \"--change\" \"LABEL com.dokku.app-name=$APP\")\ndocker commit \"${DOCKER_COMMIT_LABEL_ARGS[@]}\" $CID $IMAGE &gt;/dev/null\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-lambda","title":"<code>pre-release-lambda</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using lambda.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-pack","title":"<code>pre-release-pack</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-release-dockerfile","title":"<code>pre-release-dockerfile</code>","text":"<p>Warning</p> <p>Deprecated, please use <code>pre-release-builder</code> instead</p> <ul> <li>Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using a dockerfile.</li> <li>Invoked by: <code>internal function dokku_release() (release phase)</code></li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nsource \"$PLUGIN_CORE_AVAILABLE_PATH/common/functions\"\nAPP=\"$1\"; IMAGE_TAG=\"$2\"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-restore","title":"<code>pre-restore</code>","text":"<ul> <li>Description: Allows you to run commands before all containers are restored</li> <li>Invoked by: <code>dokku ps:restore</code></li> <li>Arguments:</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#pre-start","title":"<code>pre-start</code>","text":"<ul> <li>Description: Can be used to run commands before an app is started</li> <li>Invoked by: <code>dokku ps:start</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Notifies an example url that an app is starting\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\";\n\ncurl \"https://dokku.me/starting/${APP}\" || true\n</code></pre>"},{"location":"development/plugin-triggers/#procfile-get-command","title":"<code>procfile-get-command</code>","text":"<ul> <li>Description: Fetches the command for a specific process type</li> <li>Invoked by: <code>internally</code></li> <li>Arguments: <code>$APP $PROCESS_TYPE $PORT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#procfile-exists","title":"<code>procfile-exists</code>","text":"<ul> <li>Description: Checks if a procfile exists for the specified app</li> <li>Invoked by: <code>internally</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-build-config","title":"<code>proxy-build-config</code>","text":"<ul> <li>Description: Builds the proxy implementation configuration for a given app</li> <li>Invoked by: <code>internally triggered by ps:restore</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-clear-config","title":"<code>proxy-clear-config</code>","text":"<ul> <li>Description: Clears the proxy implementation configuration for a given app</li> <li>Invoked by: <code>internally triggered by apps:rename</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-disable","title":"<code>proxy-disable</code>","text":"<ul> <li>Description: Disables the configured proxy implementation for an app</li> <li>Invoked by: <code>internally triggered by ps:restore</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-enable","title":"<code>proxy-enable</code>","text":"<ul> <li>Description: Enables the configured proxy implementation for an app</li> <li>Invoked by: <code>internally triggered by ps:restore</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-is-enabled","title":"<code>proxy-is-enabled</code>","text":"<ul> <li>Description: Checks if there is a proxy enabled for the app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#proxy-type","title":"<code>proxy-type</code>","text":"<ul> <li>Description: Returns the proxy type for an app</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ps-can-scale","title":"<code>ps-can-scale</code>","text":"<ul> <li>Description: Sets whether or not a user can scale an app with <code>ps:scale</code></li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ps-current-scale","title":"<code>ps-current-scale</code>","text":"<ul> <li>Description: Prints out the current scale contents (process-type=quantity) delimited by newlines.</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#ps-set-scale","title":"<code>ps-set-scale</code>","text":"<ul> <li>Description: Sets the scale for an app based on a specified formation (process-type=quantity). Any unspecified process types will be left as is.</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $SKIP_DEPLOY $CLEAR_EXISTING [$PROCESS_TUPLE...]</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#receive-app","title":"<code>receive-app</code>","text":"<ul> <li>Description: Allows you to customize what occurs when an app is received. Normally just triggers an app build.</li> <li>Invoked by: <code>dokku git-hook</code>, <code>dokku ps:rebuild</code></li> <li>Arguments: <code>$APP $REV</code> (<code>$REV</code> may not be included in cases where a repository is not pushed)</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# For our imaginary mercurial plugin, triggers a rebuild\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nAPP=\"$1\"; REV=\"$2\"\n\ndokku hg-build $APP $REV\n</code></pre>"},{"location":"development/plugin-triggers/#receive-branch","title":"<code>receive-branch</code>","text":"<ul> <li>Description: Allows you to customize what occurs when a specific branch is received. Can be used to add support for specific branch names</li> <li>Invoked by: <code>dokku git-hook</code>, <code>dokku ps:rebuild</code></li> <li>Arguments: <code>$APP $REV $REFNAME</code></li> <li>Example:</li> </ul> <pre><code>#!/bin/bash\n# Gives Dokku the ability to support multiple branches for a given service\n# Allowing you to have multiple staging environments on a per-branch basis\n\nreference_app=$1\nrefname=$3\nnewrev=$2\nAPP=${refname/*\\//}.$reference_app\n\nif [[ ! -d \"$DOKKU_ROOT/$APP\" ]]; then\n  REFERENCE_REPO=\"$DOKKU_ROOT/$reference_app\"\n  git clone --bare --shared --reference \"$REFERENCE_REPO\" \"$REFERENCE_REPO\" \"$DOKKU_ROOT/$APP\" &gt;/dev/null\nfi\nplugn trigger receive-app $APP $newrev\n</code></pre>"},{"location":"development/plugin-triggers/#release-and-deploy","title":"<code>release-and-deploy</code>","text":"<ul> <li>Description: Triggers a release of the image tag and a subsequent deploy</li> <li>Invoked by:</li> <li>Arguments: <code>$APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#report","title":"<code>report</code>","text":"<ul> <li>Description: Allows you to report on any custom configuration in use by your application</li> <li>Invoked by: <code>dokku report</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#resource-get-property","title":"<code>resource-get-property</code>","text":"<ul> <li>Description: Fetches a given resource property value</li> <li>Invoked by:</li> <li>Arguments: <code>$APP</code> <code>$PROC_TYPE</code> <code>$RESOURCE_TYPE</code> <code>$PROPERTY</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROC_TYPE=\"$2\" RESOURCE_TYPE=\"$3\" PROPERTY=\"$4\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#retire-container-failed","title":"<code>retire-container-failed</code>","text":"<ul> <li>Description: Allows you to run commands if/when retiring old containers has failed</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Send an email when a container failed to retire\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; HOSTNAME=$(hostname -s)\n\nmail -s \"$APP containers on $HOSTNAME failed to retire\" ops@dokku.me\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-app-status","title":"<code>scheduler-app-status</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Fetch the status of an app</li> <li>Invoked by: <code>dokku ps:report</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-deploy","title":"<code>scheduler-deploy</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when an app is deployed</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; IMAGE_TAG=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-detect","title":"<code>scheduler-detect</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to check which scheduler is in use for an app</li> <li>Invoked by: <code>dokku deploy</code></li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-enter","title":"<code>scheduler-enter</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to enter a running container for a given app</li> <li>Invoked by: <code>dokku enter</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $@</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; ARGS=\"$@\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-inspect","title":"<code>scheduler-inspect</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run inspect commands for all containers for a given app</li> <li>Invoked by: <code>dokku ps:inspect</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-is-deployed","title":"<code>scheduler-is-deployed</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to check if the scheduler has deployed the app</li> <li>Invoked by: Various plugins</li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-logs","title":"<code>scheduler-logs</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when retrieving container logs</li> <li>Invoked by: <code>dokku logs:failed</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $PROCESS_TYPE $TAIL $PRETTY_PRINT $NUM</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; PROCESS_TYPE=\"$3\"; TAIL=\"$4\"; PRETTY_PRINT=\"$5\"; NUM=\"$6\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-logs-failed","title":"<code>scheduler-logs-failed</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when retrieving failed container logs</li> <li>Invoked by: <code>dokku logs:failed</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-pre-restore","title":"<code>scheduler-pre-restore</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run commands before an app is restored</li> <li>Invoked by: <code>dokku ps:restore</code></li> <li>Arguments: <code>$DOKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-post-delete","title":"<code>scheduler-post-delete</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when an app is deleted</li> <li>Invoked by: <code>dokku apps:destroy</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $IMAGE_TAG</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; IMAGE_TAG=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-post-deploy-process","title":"<code>scheduler-post-deploy-process</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run a command after a process has been started</li> <li>Invoked by: scheduler-docker-local</li> <li>Arguments: <code>$APP $PROCESS_TYPE</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"; PROCESS_TYPE=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-post-run","title":"<code>scheduler-post-run</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands after a <code>dokku run</code> invocation is called</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $CONTAINER_ID</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; CONTAINER_ID=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-register-retired","title":"<code>scheduler-register-retired</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows scheduling retiring a local container and any related images</li> <li>Invoked by: <code>internally</code></li> <li>Arguments: <code>$APP $CONTAINER_ID</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\";\nCONTAINER_ID=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-retire","title":"<code>scheduler-retire</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when containers should be force retired from the system</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run","title":"<code>scheduler-run</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when a command is executed for your app</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP ...ARGS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; ARGS=\"${@:3}\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run-list","title":"<code>scheduler-run-list</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Lists all run containers for a given app</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; FORMAT=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run-logs","title":"<code>scheduler-run-logs</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when retrieving one-off container logs</li> <li>Invoked by: <code>dokku run</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $CONTAINER $TAIL $PRETTY_PRINT $NUM</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; CONTAINER=\"$3\"; TAIL=\"$4\"; PRETTY_PRINT=\"$5\"; NUM=\"$6\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-run-stop","title":"<code>scheduler-run-stop</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows a scheduler to stop all \"run\" containers or a specified container</li> <li>Invoked by: <code>dokku run:stop</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $CONTAINER_NAME</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; CONTAINER_NAME=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#scheduler-stop","title":"<code>scheduler-stop</code>","text":"<p>Warning</p> <p>The scheduler plugin trigger apis are under development and may change between minor releases until the 1.0 release.</p> <ul> <li>Description: Allows you to run scheduler commands when a tag is destroyed</li> <li>Invoked by: <code>dokku apps:destroy, dokku ps:stop</code></li> <li>Arguments: <code>$DOKKU_SCHEDULER $APP $REMOVE_CONTAINERS</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nDOKKU_SCHEDULER=\"$1\"; APP=\"$2\"; REMOVE_CONTAINERS=\"$3\";\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#storage-list","title":"<code>storage-list</code>","text":"<ul> <li>Description: Returns a list of storage mounts</li> <li>Invoked by: <code>dokku storage:list</code> and <code>dokku deploy</code></li> <li>Arguments: <code>$APP $PHASE $FORMAT</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\nAPP=\"$1\"\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#traefik-template-source","title":"<code>traefik-template-source</code>","text":"<ul> <li>Description: Retrieves an alternative template for the traefik compose config</li> <li>Invoked by: traefik-vhosts</li> <li>Arguments: <code>$APP</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\n# TODO\n</code></pre>"},{"location":"development/plugin-triggers/#uninstall","title":"<code>uninstall</code>","text":"<ul> <li>Description: Used to cleanup after itself.</li> <li>Invoked by: <code>dokku plugin:uninstall</code></li> <li>Arguments: <code>$PLUGIN</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Cleanup up extra containers created\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nPLUGIN=\"$1\"\n\n[[ \"$PLUGIN\" = \"my-plugin\" ]] &amp;&amp; docker rmi -f \"${PLUGIN_IMAGE_DEPENDENCY}\"\n</code></pre> <p>To avoid uninstalling other plugins make sure to check the plugin name like shown in the example.</p>"},{"location":"development/plugin-triggers/#update","title":"<code>update</code>","text":"<ul> <li>Description: Can be used to run plugin updates on a regular interval. You can schedule the invoker in a cron-task to ensure your system gets regular updates.</li> <li>Invoked by: <code>dokku plugin:update</code>.</li> <li>Arguments: None</li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Update the herokuish image from git source\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\ncd /root/dokku\nsudo BUILD_STACK=true make install\n</code></pre>"},{"location":"development/plugin-triggers/#user-auth","title":"<code>user-auth</code>","text":"<p>This is a special plugin trigger that is executed on every command run. As Dokku sometimes internally invokes the <code>dokku</code> command, special care should be taken to properly handle internal command redirects.</p> <p>Note that the trigger should exit as follows:</p> <ul> <li><code>0</code> to continue running as normal</li> <li><code>1</code> to halt execution of the command</li> </ul> <p>The <code>SSH_USER</code> is the original ssh user. If you are running remote commands, this user will typically be <code>dokku</code>, and as such should not be trusted when checking permissions. If you are connected via ssh as a different user who then invokes <code>dokku</code>, the value of this variable will be that user's name (<code>root</code>, <code>myuser</code>, etc.).</p> <p>The <code>SSH_NAME</code> is the <code>NAME</code> variable set via the <code>sshcommand acl-add</code> command. For reference, the following command can be run as the root user to specify a specific <code>NAME</code> for a given ssh key:</p> <pre><code>sshcommand acl-add dokku NAME &lt; $PATH_TO_SSH_KEY\n</code></pre> <p>Note that the <code>NAME</code> value is set at the first ssh key match. If an ssh key is set in the <code>/home/dokku/.ssh/authorized_keys</code> multiple times, the first match will decide the value.</p> <ul> <li>Description: Allows you to deny access to a Dokku command by either ssh user or associated ssh-command NAME user.</li> <li>Invoked by: <code>dokku</code></li> <li>Arguments: <code>$SSH_USER $SSH_NAME $DOKKU_COMMAND</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# Allow root/admin users to do everything\n# Deny plugin access to default users\n# Allow access to all other commands\n\nset -eo pipefail; [[ $DOKKU_TRACE ]] &amp;&amp; set -x\n\nSSH_USER=$1\nSSH_NAME=$2\nshift 2\n[[ \"$SSH_USER\" == \"root\" ]] &amp;&amp; exit 0\n[[ \"$SSH_NAME\" == \"admin\" ]] &amp;&amp; exit 0\n[[ \"$SSH_NAME\" == \"default\" &amp;&amp; $1 == plugin:* ]] &amp;&amp; exit 1\nexit 0\n</code></pre>"},{"location":"development/plugin-triggers/#user-auth-app","title":"<code>user-auth-app</code>","text":"<p>This is a special plugin trigger that is executed when listing apps or checking if an app exists. All Dokku commands should check if an app exists at least once before interacting with them so as not to circumvent the check.</p> <p>Note that the trigger should exit <code>0</code>, and each non-empty line on stdout is captured as a valid app name.</p> <p>The <code>SSH_USER</code> is the original ssh user. If you are running remote commands, this user will typically be <code>dokku</code>, and as such should not be trusted when checking permissions. If you are connected via ssh as a different user who then invokes <code>dokku</code>, the value of this variable will be that user's name (<code>root</code>, <code>myuser</code>, etc.).</p> <p>The <code>SSH_NAME</code> is the <code>NAME</code> variable set via the <code>sshcommand acl-add</code> command. For reference, the following command can be run as the root user to specify a specific <code>NAME</code> for a given ssh key:</p> <pre><code>sshcommand acl-add dokku NAME &lt; $PATH_TO_SSH_KEY\n</code></pre> <p>Note that the <code>NAME</code> value is set at the first ssh key match. If an ssh key is set in the <code>/home/dokku/.ssh/authorized_keys</code> multiple times, the first match will decide the value.</p> <ul> <li>Description: Allows you to deny access to a Dokku app by either ssh user or associated ssh-command NAME user.</li> <li>Invoked by: <code>dokku</code></li> <li>Arguments: <code>$SSH_USER $SSH_NAME $DOKKU_COMMAND</code></li> <li>Example:</li> </ul> <pre><code>#!/usr/bin/env bash\n# hide any apps with the prefix \"admin\"\n# if the logged in user (SSH_USER) or SSH_NAME is not `root`\n\nmain() {\n  declare SSH_USER=\"$1\" SSH_NAME=\"$2\" ARGS=(\"${@:3}\")\n\n  for arg in \"${ARGS[@]}\"; do\n    if [[ \"$arg\" == admin-* ]] &amp;&amp; [[ \"$SSH_USER\" != \"root\" ]] &amp;&amp; [[ \"$SSH_NAME\" != \"root\" ]]; then\n      continue\n    fi\n\n    echo \"${arg}\"\n  done\n}\n\nmain \"$@\"\n</code></pre>"},{"location":"development/release-process/","title":"Release Process","text":"<p>Dokku is released in intervals at most three weeks apart, though may be released much quicker.</p> <p>To propose a release, the following tasks need to be performed:</p> <pre><code>export PACKAGECLOUD_TOKEN=SOME_TOKEN\n# supports major/minor/patch/betafish\ncontrib/release-dokku\n</code></pre> <p>Info</p> <p>If you are a maintainer and need the PACKAGECLOUD_TOKEN in order to make a release, please contact @josegonzalez to get this information.</p> <p>As well, the Arch Linux package description must be updated via <code>vagrant up build-arch</code> (needs to be done after the tag is pushed to GitHub, because it is based on that)</p>"},{"location":"development/release-process/#versioning","title":"Versioning","text":"<p>Dokku follows semver standards. As we are not yet at a stable release, breaking changes will require only a minor release, while all other changes only require a patch release. Once we hit stable, breaking changes will require a major release.</p> <p>At the moment, tags need not be signed, though that may change in the future.</p>"},{"location":"development/release-process/#arch-linux-packages","title":"Arch Linux Packages","text":"<p>Arch Linux packages are not really build, because all that is needed for an Arch User Repo (AUR) package is the description of how to build the package. To make this process as easy as possible there is a vagrant box called <code>build-arch</code> that updates the version of this build description (a file called <code>PKGBUILD</code>), then runs some helper scripts to fill all additional information and does test if the package could be build. Then only those changes need to be pushed to the AUR repo and an updated version of the package is ready for usage for our Arch Linux users. For detailed information see the section below.</p> <p>The workflow looks like this:</p> <pre><code># having dokku-arch in ../dokku-arch\nvagrant up build-arch\n# wait for \"==&gt; build-arch: ==&gt; Finished making: dokku 0.32.4-2 (Mon Feb 22 23:20:37 CET 2016)\"\ncd ../dokku-arch\ngit add PKGBUILD .SRCINFO\ngit commit -m 'Update to dokku 0.9.9'\ngit push aur master\n</code></pre> <p>Info</p> <p>If you are a maintainer and need access to the AUR repositories in order to make a release, please contact @morrisjobke or @josegonzalez to get this co-maintainership.</p>"},{"location":"development/release-process/#detailed-information-for-arch-linux-packages","title":"Detailed information for Arch Linux packages","text":"<p>All of the information to build the Arch Linux package is in the AUR git repository (see dokku AUR page). The release of a AUR package only consists of pushing the package information into the AUR git repo. Then users could use that information to build the package on their machines.</p> <p>To update the package clone the repository and adjust the files in the repository. Then a helper script - <code>updpkgsums</code> - to update the SHA sum could  be called (check against the original SHA sum). Another helper script - <code>mksrcinfo</code> - needs to be called to update the meta information of the package in a file called <code>.SRCINFO</code>. The next step builds the package locally for verification - <code>makepkg</code>. As last step commit your changes and push the commit.</p> <ul> <li>dependencies are defined in the <code>depends</code> attribute in <code>PKGBUILD</code></li> <li>build steps during package build time are defined in the <code>package()</code> method in <code>PKGBUILD</code></li> <li>steps that should be executed during install/update/remove time are defined in the file <code>dokku.install</code></li> <li>detailed information about all attributes in <code>PKGBUILD</code> could be found in the Arch Linux wiki</li> <li>detailed information about the AUR workflow could be found in the AUR article in the Arch Linux wiki</li> </ul> <p>That is the usual workflow:</p> <pre><code>updpkgsums # update sha sums - compare them with the original ones\nmksrcinfo # update package metadata for AUR\nmakepkg # test package builds\ngit add PKGBUILD .SRCINFO\ngit commit -m 'Update to dokku 0.9.9'\ngit push\n</code></pre>"},{"location":"development/testing/","title":"Running Tests","text":"<p>Dokku has a full test suite to assist in quick iterating development. These tests include a linter using shellcheck, functional unit tests using the Bats testing framework, and a deployment suite of example apps that use the most popular languages and frameworks.</p> <p>We maintain the Dokku test harness within the <code>tests</code> directory:</p> <ul> <li><code>tests/unit/*.bats</code>: Bats tests</li> <li><code>tests/apps/</code>: Example applications that can be used for tests</li> </ul>"},{"location":"development/testing/#continuous-integration","title":"Continuous Integration","text":"<p>All pull requests have tests run against them on GitHub Actions, a continuous integration platform that provides Docker support for Ubuntu Focal 20.04.</p> <p>If you wish to skip tests for a particular commit, e.g. documentation changes, you may add the <code>[ci skip]</code> designator to your commit message. Commits that should be tested but have the above designator will not be merged.</p> <p>While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Focal 20.04, we only provide official installation support for that platform and the latest LTS release of Ubuntu (currently 20.04).</p>"},{"location":"development/testing/#local-test-execution","title":"Local Test Execution","text":""},{"location":"development/testing/#vagrant-vm","title":"Vagrant VM","text":"<ul> <li>Setup Dokku in a Vagrant VM.</li> <li>Run the following to setup tests and execute them:</li> </ul> <pre><code>vagrant ssh\nsudo su -\ncd ~/dokku\nmake ci-dependencies setup-deploy-tests\n</code></pre> <p>After making changes to your local Dokku clone, don't forget to update the Vagrant Dokku install.</p> <pre><code># update vagrant dokku install from local git clone\nmake copyfiles\n\n# build a specific plugin\nmake go-build-plugin copyplugin PLUGIN_NAME=apps\n</code></pre>"},{"location":"development/testing/#vscode-dev-container","title":"VSCode Dev Container","text":"<ul> <li>Open Dokku in a VSCode DevContainer</li> <li>Run the following in the VSCode terminal to setup tests and execute them:</li> </ul> <pre><code>make ci-dependencies setup-deploy-tests\n</code></pre> <p>After making changes to your local Dokku clone, don't forget to update the Vagrant Dokku install.</p> <pre><code># update vagrant dokku install from local git clone\nmake copyfiles\n\n# build a specific plugin\nmake go-build-plugin copyplugin PLUGIN_NAME=apps\n</code></pre>"},{"location":"development/testing/#executing-tests","title":"Executing tests","text":"<p>Execute the entire test suite (linter, bats tests, and app deployment tests):</p> <pre><code>make test\n</code></pre> <p>Run the linter</p> <pre><code>make lint\n</code></pre> <p>Execute all bats tests</p> <pre><code>make unit-tests\n</code></pre> <p>Execute all app deployment tests</p> <pre><code>make deploy-tests\n</code></pre>"},{"location":"development/testing/#executing-app-tests","title":"Executing App Tests","text":"<p>You may run a specific app deployment tests with a target similar to:</p> <pre><code>make deploy-test-nodejs-express\n</code></pre> <p>For a full list of test make targets check out <code>tests.mk</code> in the root of the Dokku repository.</p>"},{"location":"development/testing/#executing-a-single-test-suite","title":"Executing a single test suite","text":"<p>When working on a particular plugin, it may be useful to run only a particular test suite. This can be done by specifying the test suite path:</p> <pre><code>bats tests/unit/apps_1.bats\n</code></pre> <p>It is also possible to target multiple test suites at a time.</p> <pre><code>bats tests/unit/apps_1.bats tests/unit/certs.bats\n</code></pre>"},{"location":"development/testing/#executing-a-single-test","title":"Executing a single test","text":"<p>In order to increase testing velocity, a wrapper script around Bats is available that can be used to run a single test case within a suite.</p> <p>Tests within a suite may be listed by specifying the suite as a parameter to <code>bats</code>.</p> <pre><code>bats tests/unit/apps_1.bats\n</code></pre> <p>A single test can be specified via the <code>--filter</code> argument. The tests are selected via regex match, and all matches are executed.</p> <pre><code>bats --filter list tests/unit/apps_1.bats\n</code></pre>"},{"location":"enterprise/pro/","title":"Dokku Pro","text":"<p>Dokku Pro is a commercial offering that provides a familiar Web UI for all common tasks performed by developers. End users can expect an interface that provides various complex cli commands in an intuitive, app-centric manner, quickly speeding up tasks that might otherwise be difficult for new and old users to perform. Additionally, it provides a way to perform these tasks remotely via a json api, enabling easier, audited remote management of servers. Finally, Dokku Pro provides an alternative, https-based method for deploying code which can be used in environments that lockdown ssh access to servers.</p>"},{"location":"enterprise/pro/#purchasing","title":"Purchasing","text":"<p>Dokku Pro may be purchased online by clicking the following purchase link:</p> <p>Dokku Pro Purchase Link</p> <p>Info</p> <p>Currently, the server must be able to contact the public internet to validate the license, or it will fail to start. For offline support, inquire for enterprise offline licensing.</p>"},{"location":"enterprise/pro/#installation","title":"Installation","text":"<p>Dokku Pro is shipped as Debian and RPM packages, and depends on the following files:</p> <ul> <li><code>/etc/default/dokku-pro</code>: Configures certain environment variables for usage by the dokku-pro binary</li> <li><code>/etc/dokku-pro/license.key</code>: Contains the downloaded license key</li> <li><code>/var/lib/dokku/data/pro/db</code>: Contains the local dokku-pro database</li> </ul> <p>Please refer to the purchase email for details on configuring Dokku Pro.</p>"},{"location":"enterprise/pro/#features-and-development","title":"Features and Development","text":"<p>Dokku Pro has the following functionality:</p> <ul> <li>Shipped as a single binary for ease of use</li> <li>JSON-API-compatible API with JWT authentication</li> <li>Authenticated HTTP(S) endpoints for git push functionality</li> <li>Single Page App (SPA) Web UI exposing app, datastore, and ssh key management</li> </ul> <p>While each release is fairly feature complete, individual features and documentation will expand over time. Feature development follows a monthly release cadence, with individual bug fixes released on an as needed basis.</p>"},{"location":"getting-started/advanced-installation/","title":"Advanced installation","text":""},{"location":"getting-started/advanced-installation/#installing-via-other-methods","title":"Installing via other methods","text":"<p>For various reasons, certain hosting providers may have other steps that should be preferred to the above. If hosted on any of the following popular hosts, please follow the linked to instructions:</p> <ul> <li>DigitalOcean Installation Notes</li> <li>DreamHost Cloud Installation Notes</li> <li>Microsoft Azure Installation Notes</li> </ul> <p>As well, you may wish to customize your installation in some other fashion. or experiment with Vagrant. The guides below should get you started:</p> <ul> <li>Debian Package Installation Notes</li> <li>Docker-based Installation Notes</li> <li>Vagrant Installation Notes</li> <li>Advanced Install Customization</li> <li>Automated deployment via ansible</li> </ul>"},{"location":"getting-started/advanced-installation/#installing-from-source","title":"Installing from Source","text":"<p>You can always install Dokku straight from the latest - potentially unstable - <code>master</code> branch via the following Bash command:</p> <pre><code># using a branch results in installing from source\nwget -NP . https://dokku.com/install/master/bootstrap.sh;\nsudo DOKKU_BRANCH=master bash bootstrap.sh\n</code></pre>"},{"location":"getting-started/advanced-installation/#development","title":"Development","text":"<p>If you plan on developing Dokku, the easiest way to install from your own repository is cloning the repository and calling the install script. Example:</p> <pre><code>git clone https://github.com/yourusername/dokku.git\ncd dokku\nsudo make install\n</code></pre> <p>The <code>Makefile</code> allows source URLs to be overridden to include customizations from your own repositories. The <code>DOCKER_URL</code>, <code>PLUGN_URL</code>, <code>SSHCOMMAND_URL</code> and <code>STACK_URL</code> environment variables may be set to override the defaults (see the <code>Makefile</code> for how these apply). Example:</p> <pre><code>sudo SSHCOMMAND_URL=https://raw.githubusercontent.com/yourusername/sshcommand/master/sshcommand make install\n</code></pre>"},{"location":"getting-started/advanced-installation/#bootstrap-a-server-from-your-own-repository","title":"Bootstrap a server from your own repository","text":"<p>The bootstrap script allows the Dokku repository URL to be overridden to bootstrap a host from your own clone of Dokku using the <code>DOKKU_REPO</code> environment variable. Example:</p> <pre><code>wget -NP . https://dokku.com/install/master/bootstrap.sh;\nchmod +x bootstrap.sh\nsudo DOKKU_REPO=https://github.com/yourusername/dokku.git DOKKU_BRANCH=master ./bootstrap.sh\n</code></pre>"},{"location":"getting-started/advanced-installation/#custom-herokuish-build","title":"Custom Herokuish build","text":"<p>Dokku ships with a pre-built version of version of the Herokuish component by default. If you want to build your own version you can specify that with an environment variable.</p> <pre><code>git clone https://github.com/dokku/dokku.git\ncd dokku\nsudo BUILD_STACK=true STACK_URL=https://github.com/gliderlabs/herokuish.git make install\n</code></pre>"},{"location":"getting-started/advanced-installation/#skipping-herokuish-installation","title":"Skipping Herokuish installation","text":"<p>The Herokuish package is recommended but not required if not using Heroku buildpacks for deployment. Debian-based OS users can run the bootstrap installer via <code>sudo DOKKU_NO_INSTALL_RECOMMENDS=\" --no-install-recommends \" bash bootstrap.sh</code> to skip the dependency. Please note that this will also skip installation of other recommended dependencies.</p>"},{"location":"getting-started/advanced-installation/#configuring-an-unattended-installation","title":"Configuring an unattended installation","text":"<p>Once Dokku is installed, you'll want to configure the virtualhost setup as well as the push user. If you do not, your installation will be considered incomplete and you will not be able to deploy applications.</p> <p>For Debian, unattended installation is described Debian installation guide.</p> <p>Set up a domain using your preferred vendor and a wildcard domain pointing to the host running Dokku. You can manage this global domain using the domains plugin.</p> <p>Follow the user management documentation in order to add SSH keys for users to Dokku, or to give other Unix accounts access to Dokku.</p>"},{"location":"getting-started/advanced-installation/#vms-with-less-than-1-gb-of-memory","title":"VMs with less than 1 GB of memory","text":"<p>Having less than 1 GB of system memory available for Dokku and its containers may result in unexpected errors, such as <code>! [remote rejected] master -&gt; master (pre-receive hook declined)</code> during installation of NPM dependencies.</p> <p>To work around this issue, it might suffice to augment the Linux swap file size to a maximum of twice the physical memory size.</p> <p>To resize the swap file of a 512 MB machine to 1 GB, follow these steps while in SSH within your machine:</p> <pre><code>cd /var\ntouch swap.img\nchmod 600 swap.img\n\ndd if=/dev/zero of=/var/swap.img bs=1024k count=1000\nmkswap /var/swap.img\nswapon /var/swap.img\nfree\n\necho \"/var/swap.img    none    swap    sw    0    0\" &gt;&gt; /etc/fstab\n</code></pre> <p>Reference</p>"},{"location":"getting-started/troubleshooting/","title":"Troubleshooting","text":"<p>New</p> <p>Introduced in 0.17.0</p> <pre><code>trace:on                                       # Enables trace mode\ntrace:off                                      # Disables trace mode\n</code></pre>"},{"location":"getting-started/troubleshooting/#trace-mode","title":"Trace Mode","text":"<p>By default, Dokku will constrain the amount of output displayed for any given command run. The verbosity of output can be increased by enabling trace mode. Trace mode will turn on the <code>set -x</code> flag for bash plugins, while other plugins are free to respect the environment variable <code>DOKKU_TRACE</code> and log differently as approprate. Trace mode can be useful to see where plugins are running commands that would otherwise be unexpected.</p> <p>To enable trace mode, run <code>trace:on</code></p> ShellOutput <pre><code>dokku trace:on\n</code></pre> <pre><code>-----&gt; Enabling trace mode\n</code></pre> <p>Trace mode can be disabled with <code>trace:off</code></p> ShellOutput <pre><code>dokku trace:off\n</code></pre> <pre><code>-----&gt; Disabling trace mode\n</code></pre>"},{"location":"getting-started/troubleshooting/#common-problems","title":"Common Problems","text":""},{"location":"getting-started/troubleshooting/#i-deployed-my-app-but-i-am-getting-the-default-nginx-page","title":"I deployed my app but I am getting the default nginx page","text":"<p>Most of the time it's caused by some defaults newer versions of nginx set. To make sure that's the issue you're having run the following:</p> <pre><code>nginx -t\n## nginx: [emerg] could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32\n</code></pre> <p>If you get a similar error just edit <code>/etc/nginx/nginx.conf</code> and add the following line to your <code>http</code> section:</p> <pre><code>http {\n    (... existing content ...)\n    server_names_hash_bucket_size 64;\n    (...)\n}\n</code></pre> <p>Note that the <code>server_names_hash_bucket_size</code> setting defines the maximum domain name length. A value of 64 would allow domains with up to 64 characters. Set it to 128 if you need longer ones.</p> <p>Save the file and try stopping nginx and starting it again:</p> <pre><code>dokku nginx:stop\ndokku nginx:start\n</code></pre> <p>Using the <code>EXPOSE</code> directive in a Dockerfile may be another reason why you might see the default site. When the <code>EXPOSE</code> directive is in use and a proxy plugin is enabled (the default), the proxy plugin will listen to requests on the ports specified in the <code>EXPOSE</code> stanza.</p> <p>For example, if you have an <code>EXPOSE</code> directive like so:</p> <pre><code>EXPOSE 8000\n</code></pre> <p>The port mapping will be <code>http:8000:8000</code>.</p> <p>To avoid this issue, either of the following can be done:</p> <ul> <li>Remove <code>EXPOSE</code> directive: This will require respecting the <code>$PORT</code> environment variable (automatically set by Dokku). Once that change is deployed, the port mapping should be cleared via the <code>dokku ports:clear $APP</code> command (where <code>$APP</code> is your app name).</li> <li>Update the port mapping: Updating the port mapping to redirect port <code>80</code> to your app's exposed port via <code>dokku ports:set $APP http:80:$EXPOSED_PORT</code> can also fix the issue. This will also allow certificate management and the letsencrypt plugin to work correctly.</li> </ul> <p>See the port management documentation for more information on how Dokku exposes ports for applications and how you can configure these for your app.</p>"},{"location":"getting-started/troubleshooting/#i-want-to-deploy-my-app-but-while-pushing-i-get-the-following-error","title":"I want to deploy my app, but while pushing I get the following error","text":"<p>The following error may be emitted from a deploy:</p> <pre><code>! [remote rejected] master -&gt; master (pre-receive hook declined)\n</code></pre> <p>The <code>remote rejected</code> error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a gist containing the full log, and create an issue.</p> <p>One the reasons why you may get this error is because the command that is run in the container exited (without errors). For example, (in Procfile) when you define a new worker container to run Delayed Job and use the bin/delayed_job start command. This command deamonizes the process and exists. The container thinks it's done so it closes itself. The error you get is the one above. To fix the above problem for Delayed Job, you must define the worker to user rake jobs:work, which doesn't deamonize the process.</p>"},{"location":"getting-started/troubleshooting/#i-get-the-aforementioned-error-in-the-build-phase-after-turning-on-dokku-tracing","title":"I get the aforementioned error in the build phase (after turning on Dokku tracing)","text":"<p>Most errors that happen in this phase are due to transient network issues (either locally or remotely) buildpack bugs.</p> <p>Find the failed phase's container image (<code>077581956a92</code> in this example).</p> <pre><code>docker ps -a  | grep build\n## 94d9515e6d93        077581956a92                \"/build\"       29 minutes ago      Exited (0) 25 minutes ago                       cocky_bell\n</code></pre> <p>Start a new container with the failed image and poke around (i.e. ensure you can access the internet from within the container or attempt the failed command, if known).</p> <pre><code>docker run -ti 077581956a92 /bin/bash\ncurl -s -S icanhazip.com\n## 192.168.0.1\ncurl http://s3pository.heroku.com/node/v0.10.30/node-v0.10.30-linux-x64.tar.gz -o node-v0.10.30-linux-x64.tar.gz\ntar tzf node-v0.10.30-linux-x64.tar.gz\n## ...\n</code></pre> <p>Sometimes (especially on DigitalOcean) deploying again seems to get past these seemingly transient issues. Additionally we've seen issues if changing networks that have different DNS resolvers. In this case, you can run the following to update your <code>resolv.conf</code>.</p> <pre><code>resolvconf -u\n</code></pre> <p>Please see #841 and #649.</p>"},{"location":"getting-started/troubleshooting/#after-adding-an-ssh-key-i-am-told-i-cannot-read-from-the-remote-repository-on-push","title":"After adding an SSH key, I am told I cannot read from the remote repository on push","text":"<pre><code>Connection closed by &lt;host&gt; port 22\nfatal: Could not read from remote repository.\n\nPlease make sure you have the correct access rights\nand the repository exists.\n</code></pre> <p>Certain systems may have access to the <code>dokku</code> user via SSH disabled. Please check that the <code>dokku</code> user is allowed access to the system in the file <code>/etc/security/access.conf</code>. As Dokku does not manage this file, please consult your Operating System's documentation for more information.</p>"},{"location":"getting-started/troubleshooting/#i-want-to-deploy-my-app-but-i-am-getting-asked-for-the-password-of-the-git-user","title":"I want to deploy my app but I am getting asked for the password of the Git user","text":"<p>Sometimes the following error message may be shown on push</p> <pre><code>fatal: 'NAME' does not appear to be a git repository\nfatal: Could not read from remote repository.\n</code></pre> <p>You get asked for a password because your SSH secret key can't be found. This may happen if the private key corresponding to the public key you added with <code>sshcommand acl-add</code> is not located in the default location <code>~/.ssh/id_rsa</code>.</p> <p>You have to point SSH to the correct secret key for your domain name. Add the following to your <code>~/.ssh/config</code>:</p> <pre><code>Host DOKKU_HOSTNAME\n  IdentityFile \"~/.ssh/KEYNAME\"\n</code></pre> <p>Also see issue #116.</p>"},{"location":"getting-started/troubleshooting/#i-successfully-deployed-my-application-with-no-deployment-errors-and-receiving-bad-gateway-when-attempting-to-access-the-application","title":"I successfully deployed my application with no deployment errors and receiving Bad Gateway when attempting to access the application","text":"<p>In many cases the application will require the a <code>process.env.PORT</code> port opposed to a specified port.</p> <p>When specifying your port you may want to use something similar to:</p> <pre><code>var port = process.env.PORT || 3000\n</code></pre> <p>Please see #282.</p> <p>Additionally, your application should listen/bind to all interfaces (<code>0.0.0.0</code>). Many frameworks default to listening on <code>127.0.0.1</code>.</p> <p>Please see #5798.</p>"},{"location":"getting-started/troubleshooting/#deployment-fails-because-of-slow-internet-connection-messages-shows-gzip-stdin-unexpected-end-of-file","title":"Deployment fails because of slow internet connection, messages shows <code>gzip: stdin: unexpected end of file</code>","text":"<p>If you see output similar this when deploying:</p> <pre><code> Command: 'set -o pipefail; curl --fail --retry 3 --retry-delay 1 --connect-timeout 3 --max-time 30 https://s3-external-1.amazonaws.com/heroku-buildpack-ruby/ruby-2.0.0-p451-default-cache.tgz -s -o - | tar zxf -' failed unexpectedly:\n !\n !     gzip: stdin: unexpected end of file\n !     tar: Unexpected EOF in archive\n !     tar: Unexpected EOF in archive\n !     tar: Error is not recoverable: exiting now\n</code></pre> <p>it might that the cURL command that is supposed to fetch the buildpack (anything in the low megabyte file size range) takes too long to finish, due to slowish connection.  To overwrite the default values (connection timeout: 90 seconds, total maximum time for operation: 600 seconds), set the following environment variables:</p> <pre><code>dokku config:set --global CURL_TIMEOUT=1200\ndokku config:set --global CURL_CONNECT_TIMEOUT=180\n</code></pre> <p>Please see #509.</p> <p>Another reason for this error (although it may respond immediately ruling out a timeout issue) may be because you've set the config setting <code>SSL_CERT_FILE</code>. Using a config setting with this key interferes with the buildpack's ability to download its dependencies, so you must rename the config setting to something else, e.g. <code>MY_APP_SSL_CERT_FILE</code>.</p>"},{"location":"getting-started/troubleshooting/#build-fails-with-killed-message","title":"Build fails with <code>Killed</code> message","text":"<p>This generally occurs when the server runs out of memory. You can either add more RAM to your server or setup swap space. The follow script will create 2 GB of swap space.</p> <pre><code>sudo install -o root -g root -m 0600 /dev/null /swapfile\ndd if=/dev/zero of=/swapfile bs=1k count=2048k\nmkswap /swapfile\nswapon /swapfile\necho \"/swapfile       swap    swap    auto      0       0\" | sudo tee -a /etc/fstab\nsudo sysctl -w vm.swappiness=10\necho vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf\n</code></pre>"},{"location":"getting-started/troubleshooting/#i-successfully-deployed-my-application-with-no-deployment-errors-but-im-receiving-connection-timeout-when-attempting-to-access-the-application","title":"I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application","text":"<p>This can occur if Dokku is running on a system with a firewall like UFW enabled (some OS versions like Ubuntu have this enabled by default). You can check if this is your case by running the following script:</p> <pre><code>sudo ufw status\n</code></pre> <p>If the previous script returned <code>Status: active</code> and a list of ports, UFW is enabled and is probably the cause of the symptom described above. To disable it, run:</p> <pre><code>sudo ufw disable\n</code></pre>"},{"location":"getting-started/troubleshooting/#i-cant-connect-to-my-application-because-the-server-is-sending-an-invalid-response-or-cant-provide-a-secure-connection","title":"I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection","text":"<p>This isn't usually an issue with Dokku, but rather an app config problem. This can happen when your application is configured to enforce secure connections/HSTS, but you don't have SSL set up for the app.</p> <p>In Rails at least, if your <code>application.rb</code> or <code>environmnents/production.rb</code> include the line <code>configure.force_ssl = true</code> which includes HSTS, try commenting that out and redeploying.</p> <p>If this solves the issue temporarily, longer term you should consider configuring SSL.</p>"},{"location":"getting-started/troubleshooting/#my-application-deploys-properly-but-wont-load-in-browser-connection-refused","title":"My application deploys properly, but won't load in browser \"connection refused\"","text":"<p>This could be a result of a bad proxy configuration (<code>http:5000:5000</code> may be incorrect). Run <code>dokku ports:report node-js-app</code> to check if your app has the correct proxy configuration. It should show something like the following.</p> <pre><code>=====&gt; node-js-app ports information\n       Port map:                http:80:5000 https:443:5000\n</code></pre> <p>Set <code>dokku ports:set node-js-app http:80:5000</code> to get proxy correctly configured for http endpoint.</p>"},{"location":"getting-started/troubleshooting/#i-deployed-a-new-app-but-now-subdomains-are-miss-routed","title":"I deployed a new app but now subdomains are miss-routed","text":"<p>Sometimes nginx does something funky and cant actually reload for whatever reason.</p> <pre><code># Validate the configuration\n$ sudo nginx -t\nnginx: the configuration file /etc/nginx/nginx.conf syntax is ok\nnginx: configuration file /etc/nginx/nginx.conf test is successful\n\n$ sudo service nginx restart\n\n# Re-enable Letsencrypt\n</code></pre> <p>Example: existing AppA (https) and AppB(https), deployed NEW (non-https) then noticed right away NEW's subdomain showed AppB's content and cert but under its own subdomain (cert miss-match of course).  AppB still works.  AppA also changed to show AppB content and cert..  Other apps were unaffected.</p> <p>Consider caddy and traefik support via docker containers if this continues to be an issue.</p>"},{"location":"getting-started/uninstalling/","title":"Uninstalling","text":"<p>While we hate to see you go, if you need to uninstall Dokku, the following may help you out:</p>"},{"location":"getting-started/uninstalling/#arch-uninstallation","title":"Arch Uninstallation","text":"<pre><code># purge dokku from your system\nyay -Rsn dokku\n</code></pre>"},{"location":"getting-started/uninstalling/#debian-uninstallation","title":"Debian Uninstallation","text":"<pre><code># purge dokku from your system\napt-get purge dokku herokuish\n\n# remove any dependencies that are no longer necessary\napt-get autoremove\n</code></pre>"},{"location":"getting-started/uninstalling/#makefile-uninstallation","title":"Makefile Uninstallation","text":"<p>This is a manual deletion process, and as it is not a recommended installation method, there is currently no automated uninstallation.</p> <p>All service plugins should be unlinked from applications, stopped, and destroyed.</p> <p>All applications should be stopped, and all docker containers and images deleted:</p> <pre><code># stop all applications\ndokku ps:stop --all\n\n# cleanup containers and images\ndokku cleanup\n</code></pre> <p>The following user/group must be deleted:</p> <ul> <li>user: <code>dokku</code></li> <li>group: <code>dokku</code></li> </ul> <p>The following directories must be deleted:</p> <ul> <li><code>~dokku</code></li> <li><code>/var/lib/dokku</code></li> <li><code>/var/log/dokku</code></li> </ul>"},{"location":"getting-started/where-to-get-help/","title":"Where to Get Help","text":"<p>If you\u2019re stuck, there are a number of places you can get help:</p>"},{"location":"getting-started/where-to-get-help/#the-official-dokku-website","title":"The Official Dokku Website","text":"<ul> <li>https://dokku.com/docs/</li> </ul> <p>The Official Dokku website is always a great place to visit. It features links to oft-used developer tools, community plugins, and guides on using Dokku.</p>"},{"location":"getting-started/where-to-get-help/#monitored-locations","title":"Monitored Locations","text":"<p>The Code Of Conduct applies to all actively monitored Dokku discussion areas. Please be mindful of your neighbors on the internet.</p>"},{"location":"getting-started/where-to-get-help/#forums","title":"Forums","text":"<ul> <li>GitHub Discussions</li> </ul> <p>GitHub Discussions is a new way for the Dokku community to interact with each other! This is a place to ask questions to the community or discuss potential feature requests before filing issues.</p>"},{"location":"getting-started/where-to-get-help/#the-slack-channel","title":"The Slack Channel","text":"<ul> <li>Gliderlabs Slack (Join the <code>#dokku</code> channel)</li> </ul> <p>If you\u2019re stumped, give us a holler in the Dokku Slack channel. Someone from the development team is usually there, especially during the daylight hours for North and South American users. We\u2019d love to hear from you, whether you need some help, want to find users in your area, or would like to donate our brand new sports car.</p> <p>Chat is synced to Discord and IRC.</p>"},{"location":"getting-started/where-to-get-help/#discord","title":"Discord","text":"<ul> <li>Dokku Discord</li> </ul> <p>We provide a Dokku Discord that folks can use to ask questions or comments about the project. Someone from the development team is usually there, especially during the daylight hours for North and South American users. Feel free to join us online!</p> <p>Chat is synced to IRC and Slack.</p>"},{"location":"getting-started/where-to-get-help/#unmonitored-locations","title":"Unmonitored Locations","text":"<p>You may find help on these locations, but they are not actively monitored by the development team. The Code of Conduct still applies.</p>"},{"location":"getting-started/where-to-get-help/#stack-overflow","title":"Stack Overflow","text":"<ul> <li>The Dokku tag on Stack Overflow</li> </ul> <p>Tag your questions with <code>dokku</code> to enable existing users of Stack Overflow to find your questions.</p>"},{"location":"getting-started/where-to-get-help/#irc-on-liberachat","title":"IRC (on libera.chat)","text":"<ul> <li>irc.libera.chat/#dokku</li> </ul> <p>This location isn't as well monitored as Slack, and loses history. Chat is synced to Discord and Slack</p>"},{"location":"getting-started/install/azure/","title":"Microsoft Azure Installation Notes","text":"<ol> <li> <p>If you don't already have one generate an SSH key pair.</p> </li> <li> <p>Go to the Dokku on Azure deployment page and click Deploy to Azure.</p> </li> <li> <p>You'll be prompted to enter a few parameters, including a unique storage account name and a unique name for the subdomain used for your public IP address. For the <code>sshKeyData</code> parameter, copy and paste the contents of the public key file you just created. After a few minutes the Dokku instance will be deployed.</p> </li> <li> <p>Once the installation is complete, you should configure an ssh key and set your global domain.</p> <pre><code># usually your key is already available under the current user's `~/.ssh/authorized_keys` file\ncat ~/.ssh/authorized_keys | dokku ssh-keys:add admin\n\n# you can use any domain you already have access to\n# this domain should have an A record or CNAME pointing at your server's IP\ndokku domains:set-global dokku.me\n\n# you can also use the ip of your server\ndokku domains:set-global 10.0.0.2\n\n# finally, you can use sslip.io to get subdomain support\n# as you would with a regular domain name\n# this would be done by appending `.sslip.io` to your ip address\ndokku domains:set-global 10.0.0.2.sslip.io\n</code></pre> </li> </ol> <p>See the user management and domains documentation for more information.</p>"},{"location":"getting-started/install/debian/","title":"Debian Package Installation Notes","text":"<p>As of 0.3.18, Dokku defaults to being installed via Debian package. While certain hosts may require extra work to get running, you may optionally wish to automate the installation of Dokku without the use of our <code>bootstrap.sh</code> Bash script. The following are the steps run by said script:</p> <pre><code># install prerequisites\nsudo apt-get update -qq &gt;/dev/null\nsudo apt-get -qq -y --no-install-recommends install apt-transport-https\n\n# install docker\nwget -nv -O - https://get.docker.com/ | sh\n\n# install dokku\nwget -qO- https://packagecloud.io/dokku/dokku/gpgkey | sudo tee /etc/apt/trusted.gpg.d/dokku.asc\n# programmatically determine distro and codename\nDISTRO=\"$(awk -F= '$1==\"ID\" { print tolower($2) ;}' /etc/os-release)\"\nOS_ID=\"$(awk -F= '$1==\"VERSION_CODENAME\" { print tolower($2) ;}' /etc/os-release)\"\necho \"deb https://packagecloud.io/dokku/dokku/${DISTRO}/ ${OS_ID} main\" | sudo tee /etc/apt/sources.list.d/dokku.list\nsudo apt-get update -qq &gt;/dev/null\nsudo apt-get -qq -y install dokku\nsudo dokku plugin:install-dependencies --core\n</code></pre>"},{"location":"getting-started/install/debian/#unattended-installation","title":"Unattended installation","text":"<p>In case you want to perform an unattended installation of Dokku, this is made possible through debconf, which allows you to configure a package before installing it.</p> <p>You can set any of the below options through the <code>debconf-set-selections</code> command, for example to enable vhost-based deployments:</p> <pre><code>echo \"dokku dokku/vhost_enable boolean true\" | sudo debconf-set-selections\n</code></pre> <p>After setting the desired options, proceed with the installation as described above.</p>"},{"location":"getting-started/install/debian/#debconf-options","title":"debconf options","text":"Name Type Default Description dokku/vhost_enable boolean false Use vhost-based deployments (e.g. <code>[yourapp].dokku.me</code>) dokku/hostname string dokku.me Hostname, used as vhost domain and for showing app URL after deploy dokku/skip_key_file boolean false Don't check for the existence of the dokku/key_file. Warning: Setting this to true, will require you to manually add an SSH key later on. dokku/key_file string /root/.ssh/id_rsa.pub Path on disk to an SSH key to add to the Dokku user (Will be ignored on <code>dpkg-reconfigure</code>) dokku/nginx_enable boolean true Enable nginx-vhosts plugin"},{"location":"getting-started/install/digitalocean/","title":"DigitalOcean Droplet Installation Notes","text":"<p>DigitalOcean offers a pre-installed Dokku image. You can run this image on any sized Droplet, although larger Droplets will allow you to run larger applications.</p> <p>Info</p> <p>Please disable IPv6. There are known issues with IPv6 on DigitalOcean and Docker. If you would like to run Dokku on an IPv6 DigitalOcean Droplet, please consult this guide.</p> <ol> <li>Login to your DigitalOcean account.</li> <li>Click Create a Droplet.</li> <li>Under Choose an image &gt; Marketplace, search latest Dokku release for Ubuntu 20.04 (version numbers may vary).</li> <li>Under Choose a size, select your machine spec.</li> <li>Under Choose a datacenter region, select your region.</li> <li>Add an SSH Key.</li> <li>New Keys<ol> <li>Under Add your SSH keys click New SSH Key (this opens a dialog).</li> <li>From your terminal, execute <code>cat $HOME/.ssh/id_rsa.pub</code>.</li> <li>Copy the output and paste it into the New SSH Key dialog, provide a name and click Add SSH Key.</li> </ol> </li> <li>Existing Keys<ol> <li>Simply add a checkmark next to the existing keys you'd like to add.</li> </ol> </li> <li>Under Finalize and create, give your Droplet a hostname (not required) and click Create.</li> <li>Once created, copy the IP address to your clipboard.</li> <li>In a browser, go to the IP address you copied above and fill out the presented form to complete configuration. Failure to do so may allow others to reconfigure SSH access on your server.</li> <li>Once the web UI has been submitted, you will be redirected to our application deployment tutorial, which will guide you through deploying a sample application to your Dokku server.</li> </ol>"},{"location":"getting-started/install/docker/","title":"Docker Installation Notes","text":"<p>Pull the dokku/dokku image:</p> <pre><code>docker pull dokku/dokku:0.32.4\n</code></pre> <p>Next, run the image.</p> <pre><code>docker container run \\\n  --env DOKKU_HOSTNAME=dokku.me \\\n  --env DOKKU_HOST_ROOT=/var/lib/dokku/home/dokku \\\n  --env DOKKU_LIB_HOST_ROOT=/var/lib/dokku/var/lib/dokku \\\n  --name dokku \\\n  --publish 3022:22 \\\n  --publish 8080:80 \\\n  --publish 8443:443 \\\n  --volume /var/lib/dokku:/mnt/dokku \\\n  --volume /var/run/docker.sock:/var/run/docker.sock \\\n  dokku/dokku:0.32.4\n</code></pre> <p>The above command will start a new docker container that is ready when a message similar to <code>Runit started as PID 12345</code> appears.</p> <p>Dokku is run in the following configuration:</p> <ul> <li>The global hostname is set to <code>dokku.me</code> on boot.</li> <li>The container name is dokku.</li> <li>Container SSH port 22 is exposed on the host as 3022.</li> <li>Container HTTP port 80 is exposed on the host as 8080.</li> <li>Container HTTPS port 443 is exposed on the host as 8443.</li> <li>Data within the container is stored on the host within the <code>/var/lib/dokku</code> directory.</li> <li>Image build cache is set to the data dir + <code>/home/dokku</code>.</li> <li>The docker socket is mounted into container.</li> </ul> <p>Application repositories, plugin config, as well as plugin data are persisted to disk within the specified host directory for <code>/var/lib/dokku</code>.</p> <p>Other docker container options can also be used when running Dokku, though the specific outcome will depend upon the specified options. For example, the Dokku container's nginx port can be bound to a specific host ip by specifying <code>--publish $HOST_IP:8080:80</code>, where <code>$HOST_IP</code> is the IP desired. Please see the docker container run documentation for further explanation for various docker arguments.</p>"},{"location":"getting-started/install/docker/#plugin-installation","title":"Plugin Installation","text":""},{"location":"getting-started/install/docker/#on-dokku-start","title":"On Dokku start","text":"<p>To install custom plugins, create a <code>plugin-list</code> file in the host's <code>/var/lib/dokku</code> directory. The plugins listed herein will be automatically installed by Dokku on container boot. This file should be the following format:</p> <pre><code>plugin_name: repository_url\n</code></pre> <p>An example for installing the postgres and redis plugins follows:</p> <pre><code>postgres: https://github.com/dokku/dokku-postgres.git\nredis: https://github.com/dokku/dokku-redis.git\n</code></pre>"},{"location":"getting-started/install/docker/#prior-to-dokku-start","title":"Prior to Dokku start","text":"<p>The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any <code>plugin:install</code> command. Note that the version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.</p> <pre><code>FROM dokku/dokku:0.32.4\nRUN dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres\nRUN dokku plugin:install https://github.com/dokku/dokku-redis.git redis\n</code></pre>"},{"location":"getting-started/install/docker/#ssh-key-management","title":"SSH Key Management","text":"<p>To initialize ssh-keys within the container, use <code>docker exec</code> to enter the container and run the appropriate ssh-keys commands.</p> <pre><code>docker exec -it dokku bash\n</code></pre> <p>Please see the user management documentation for more information.</p>"},{"location":"getting-started/install/docker/#pushing-applications","title":"Pushing Applications","text":"<p>When exposing the Dokku container's SSH port (22) on 3022, something similar to the following will need to be setup within the user's <code>~/.ssh/config</code>:</p> <pre><code>Host dokku.docker\n  HostName 127.0.0.1\n  Port 3022\n</code></pre> <p>In the above example, the hostname <code>127.0.0.1</code> is being aliased to <code>dokku.docker</code>, while the port is being overriden to <code>3022</code>. All SSH commands - including git pushes - for the hostname <code>dokku.docker</code> will be transparently sent to <code>127.0.0.1:3022</code>.</p>"},{"location":"getting-started/install/dreamhost/","title":"DreamHost Cloud Server Installation Notes","text":"<p>Cloud-init script can be used to automate installation of Dokku on Dreamhost (or any other OpenStack-compatible cloud with minimal changes).</p> <p>A new server instance can be created on DreamHost Cloud from the command line using OpenStack client or from the web UI and with the same command use a cloud-init script to install Dokku. Install the OpenStack CLI, download the DreamHost Cloud credentials file before proceeding and make sure your public SSH key is added to the cloud.</p> <pre><code>source openrc.sh # Set the environment variables for DreamHost Cloud\n</code></pre> <p>This allows OpenStack client to connect to DreamHost API endpoints. The command below creates a new server instance named <code>my-dokku-instance</code> based on Ubuntu 20.04, with 2 GB RAM and 1 CPU (the flavor called <code>supersonic</code>), opening network port access to HTTP and SSH (the <code>default</code> security group), and the name of the chosen SSH key. This key will be automatically added to the new server in the <code>authorized_keys</code> for the default SSH user (<code>ubuntu</code>), and it will be reused by Dokku.</p> <pre><code>openstack server create \\\n  --image Ubuntu-20.04 \\\n  --flavor gp1.supersonic \\\n  --security-group default \\\n  --key-name $YOUR_SSH_KEYNAME \\\n  --user-data dokku-cloudinit.sh \\\n  my-dokku-instance\n</code></pre> <p>The content of dokku-cloudinit.sh script contains instructions to add Docker and Dokku's apt repositories and install Dokku with the proper debconf options set. Don't forget to add the FQDN for your application server:</p> <pre><code>#cloud-config\n\napt:\n  sources:\n    source_dokku: \n      source: 'deb https://packagecloud.io/dokku/dokku/ubuntu/ $RELEASE main'\n      key: |\n        -----BEGIN PGP PUBLIC KEY BLOCK-----\n        Version: GnuPG v1.4.11 (GNU/Linux)\n\n        mQINBFu7hksBEADJfS1wB4JJmVcJ3FYoY/F3DmEsg2/NSj/TleB7hkdFPGTaOEef\n        c6SrK6bkQas8CzCZXskg3FFUFyxJwP0yQFosJ7nQCXbuaCzkGyOaob/2D4lqniKu\n        lyFvZuN0Evh2SoJYB6Idiy3rG58/KMQxJ/73HjcrOPxwpcfIE+rfey0fo6HOcSz7\n        AS3pXMbe0VoVOt8107i9qg6PizpaPugbSOP98aq2o0sPkjvKVzPsBvXWe9lDTreI\n        X+00Z6WXjcDxmKTGvCkcJ6jk0L5r66Y6TNlJeYwFb0o7PbY7YeJSEJxw9eNozZpY\n        EYvHCzHvsv7c8s+s5MeHDvvF5qsvt5qPPfw3zwLT01g1YTQpZdSDKn72YhrQUGJM\n        j/W8ro8Ij9BYhYQMIdy+RPNQrBdKjj75kW1NLCGLlE89+6PYzlQwDFLdl9eZlUdM\n        rvxbDPM99MRBBq30xfIS6YctHr40mEqZEi6OUoImaj5bbA1H3XHVH2JsWo1ttQYo\n        5qOGGhNi7/nyI9zxVo9r97lgGLztyl6ILZt8kxnWIx1QnPmSMuUNqYfuUuKAPs1q\n        +bisBLvylnFvQSqnpEuPwUS1UDby4CzVBzshTsuykCQRiwdU9tcjzZUlKKKTRLhj\n        CZCNxv1Ovgl+3m/4R5L7YOBYGCmVW0/GvlrxPLGCjZa1O8/3nih5+cv5TwARAQAB\n        tGhodHRwczovL3BhY2thZ2VjbG91ZC5pby9kb2trdS9kb2trdSAoaHR0cHM6Ly9w\n        YWNrYWdlY2xvdWQuaW8vZG9jcyNncGdfc2lnbmluZykgPHN1cHBvcnRAcGFja2Fn\n        ZWNsb3VkLmlvPokCOAQTAQIAIgUCW7uGSwIbLwYLCQgHAwIGFQgCCQoLBBYCAwEC\n        HgECF4AACgkQ8f9oUSiLMxUN3Q/+LeoFr8p3zSp9tRcCuMXfbc7rnJ/UgJiO53jW\n        8LsXH1h5dWeh2H5VqzGjDJ3SORisAWdOMu1SWkw4mvBZQQL12iwAMZmIDmbWU73c\n        PplwGUQ4sltNxtiAVdntWC1vwSceY6/AQZwE2k60RYzg5bR2KAyZR9yGssGsekFO\n        zOuMiTswzEYoZaJla+cduAXZzGf8NZgbzhXKhyfjVodRTyNR0dhoeMwNBlH0WWzW\n        owwNOaJQ1LwDUkjrfRpkT53RJ5olRYa5ONDxuZEvmFy57bqXJh5U13m9FNWEtmF2\n        NySFltZYEL6BZQn5qehF4kqqJ0JSVsHEyEC7sU9yr93khTGjWQfcGaITZXPNyXTC\n        py/J1TeOEOz2VyvglPx/JL4dTfPg5uZCTWRXzLJDAbW26BcyFI4OyPjFly6FLj0o\n        nMUuEzdCmNpHCKWkeyXajxtYd4EMo+UHGYC7jrpsAxRib0pdHUwnOG0MeNIUtPm/\n        yW8i5St9PnX2y2qSaAoVURAI3irApn4Wc+hgRjo22l/B6ZudMAtASD5Ie8pXHNS0\n        dlsgiv3sTZachMKU+usoIgejIb0MuBhBwVJ93A4YguEqNgZg0Cz4MUpWNma6zLIN\n        Ko+3khp3z2Y/jWfNTKs41sz++png1iqjnvXjGIjKtgcFJyH+AwZzkh5LjRiahM/I\n        OO/xTaO5Ag0EW7uGSwEQAL39qC95IFVNobRvecddeL26kHPgd0JS4fjB5r01pMFR\n        3fojnEwGTLzRJVR4iTfzOiAG1XKGYmEb15NkEgEcvaLaojSsaaAHv++BqL2qXHJa\n        sfsgjKqxCAKyJps5wCEIzF1xfxHB/5BIyKenXZw9K/zlZzsfqzyehLAarZ4oMQEN\n        u/dG3TlXCf/oSBHDttLTcRTGs1I8FEaA9O0ZeV+2S/WuT0kFa6s1tRUMMWHWzMmR\n        2a+vLCE3OMWtlRk6sfhfccf4rIzjj3xyieEGKznkOycu8JOqTBRmGMl3wRS2XI7c\n        PFiV1MGRV5uhJ6a0D6DDAddL13TaXMfsZB0KkFHh8bKvAxJA9opHhl+X2NrdwsLz\n        crCWF+QdoPX494j2aWnwSOXXtW9c2b6cpDfUoGVD79IYEzL0n6dgBPwCKLcmxotF\n        Tv+H3Yy0DBn8BaQ0ZHbEgudwr73vxMgbYStGfu/bQEulcLA0vfTRGBRhzlZLE8k6\n        +fXK23R4T/3kdyJovHdnK6aIN6oFTnVM5pyLrxmUkLCaPEbnoxVtA9zOeiGhqjYT\n        pLgZMG95HgoscBlOh8BpuM2E3MSPV6XYjEKtvDpWy/i/oCPhd/PcY/qVxzj6dANU\n        gQE/8hdf6Q//SvUxZaVrVwnmWkIZshGDJj/EM8VGhKzEoZF8Xmr/aibyN3CLoSMl\n        ABEBAAGJBD4EGAECAAkFAlu7hksCGy4CKQkQ8f9oUSiLMxXBXSAEGQECAAYFAlu7\n        hksACgkQ+ytqpCHNGT+1Vg//Z0ZiIoQQCLXmbAPdA79HVLCzsvkKQ3/RlqIR7Nq1\n        JzgqPxg8drRo5+Ri+VrsIJt3AYH/lGm1UuSeycM6NrNWBpqL5FLjrMmbILQp9GMf\n        bCZLXocOwDvrfpdBuEK+AS8SuLeiZtl8DcOe9Xtv3LSxXre0hsiIZpTRIjP+qkj8\n        W7oZqUxwo1Wcnff+0snf6hPiTps/IB1utzSjxXVe86/89BWvLt/mT1o81h5mclgk\n        l1eit6BvZsO/iicLB5KbyA7DVjAnxngze0+cCUAIVbqQbZhAVw5oZbKeXedbGuxr\n        eRLWx+h5IBbtn+JwWngzueHyc3fY5b6ann06f6y6BF5+XmPRIXakYh4moJxSRQCA\n        GVKGEubH/Y1Vyq8QIX7V6PGpS39mQkoYXEztvEtyZiV3J+SyObYZVTs9d5/rhoE2\n        wXQIFTOdyHi52K2VfT3JU7rWOw5/SWuOQyyDdWgxEJuU6bUeOViOwHVkZDzwBX3Y\n        1to5cgY6dNQARplEgZZjRja4uc06u2d7Bk2CfqO4LvjV5UlPm838Ga+kGzBpp86X\n        5JBbZz9lPGf+GY7ZcROQp6ONui8P08+7EaTVtILTE0rd5g8umOnWBo1zteMv50As\n        jyIPW20kUuJMdz3V+TNag5aCMW7qnO4zwildlQZmL54+xQDuRXK8P5JlKml6gnK+\n        4SLvUA/8CALEMqxNlb06ZJc1GCU/mcQYXfkNosHaNYpORjziDnH1LBQ7AnhIhhMy\n        FwcuxpG9bABwQfoQE84Kx3zVU0xEoCGr549Kf5p7ZcqGwn3WzSql+qR/NcPRV9Dp\n        tb4iSXoTUeutR1SeVn/TI2aOWez3UyIztnam+p32e4BNuyByFRmo2e8dP1RqCg6b\n        0KwuxDDE0k3zJCpjsWROrtBVQ9Zt9rsfG5kFxJ6Qi90uJP71f8rFDUuKmxJazDf3\n        g3GHEGovUrOJO5JpvCcfCyT9mfOPxUSAKGBHj8NPY84vjqGaA9qqt54D8YT57TjR\n        5oWd8Iwex4XFHAoj59q04KmramVgP5q8VKFrxwVOhYmK6SNmvW9dEI3Y16bu9KF7\n        CJnPq/mQXEI+a/G6hZgZ8eYxOV2812WcORppezALreHJeN1HogxI972G0kalKhNC\n        p3315BKJdw/p6/j/qIob2EZOdqBsdHRKBgBVXVbaCnzgh1kKLEvJnVDio+zjEPDr\n        lR9wQbcHRbu+ZqRSEbH0of/4rx0CdCPGKSDafviKPDXnvls85tWV/lMtNxamqYvv\n        V0DUeTWQDmfiyWCgqXTiRA9U4ZFgFNWmirh38UmV7VtSlYaRos8fEQTfmN20fqTk\n        9mVAREENSiAuc4P93l8TtrN1bAqXaTX5oz+lepqWmHWvY+RiNiw=\n        =laU4\n        -----END PGP PUBLIC KEY BLOCK-----\n    source_docker: \n      source: 'deb [arch=amd64] https://download.docker.com/linux/ubuntu $RELEASE stable'\n      key: |\n        -----BEGIN PGP PUBLIC KEY BLOCK-----\n\n        mQINBFit2ioBEADhWpZ8/wvZ6hUTiXOwQHXMAlaFHcPH9hAtr4F1y2+OYdbtMuth\n        lqqwp028AqyY+PRfVMtSYMbjuQuu5byyKR01BbqYhuS3jtqQmljZ/bJvXqnmiVXh\n        38UuLa+z077PxyxQhu5BbqntTPQMfiyqEiU+BKbq2WmANUKQf+1AmZY/IruOXbnq\n        L4C1+gJ8vfmXQt99npCaxEjaNRVYfOS8QcixNzHUYnb6emjlANyEVlZzeqo7XKl7\n        UrwV5inawTSzWNvtjEjj4nJL8NsLwscpLPQUhTQ+7BbQXAwAmeHCUTQIvvWXqw0N\n        cmhh4HgeQscQHYgOJjjDVfoY5MucvglbIgCqfzAHW9jxmRL4qbMZj+b1XoePEtht\n        ku4bIQN1X5P07fNWzlgaRL5Z4POXDDZTlIQ/El58j9kp4bnWRCJW0lya+f8ocodo\n        vZZ+Doi+fy4D5ZGrL4XEcIQP/Lv5uFyf+kQtl/94VFYVJOleAv8W92KdgDkhTcTD\n        G7c0tIkVEKNUq48b3aQ64NOZQW7fVjfoKwEZdOqPE72Pa45jrZzvUFxSpdiNk2tZ\n        XYukHjlxxEgBdC/J3cMMNRE1F4NCA3ApfV1Y7/hTeOnmDuDYwr9/obA8t016Yljj\n        q5rdkywPf4JF8mXUW5eCN1vAFHxeg9ZWemhBtQmGxXnw9M+z6hWwc6ahmwARAQAB\n        tCtEb2NrZXIgUmVsZWFzZSAoQ0UgZGViKSA8ZG9ja2VyQGRvY2tlci5jb20+iQI3\n        BBMBCgAhBQJYrefAAhsvBQsJCAcDBRUKCQgLBRYCAwEAAh4BAheAAAoJEI2BgDwO\n        v82IsskP/iQZo68flDQmNvn8X5XTd6RRaUH33kXYXquT6NkHJciS7E2gTJmqvMqd\n        tI4mNYHCSEYxI5qrcYV5YqX9P6+Ko+vozo4nseUQLPH/ATQ4qL0Zok+1jkag3Lgk\n        jonyUf9bwtWxFp05HC3GMHPhhcUSexCxQLQvnFWXD2sWLKivHp2fT8QbRGeZ+d3m\n        6fqcd5Fu7pxsqm0EUDK5NL+nPIgYhN+auTrhgzhK1CShfGccM/wfRlei9Utz6p9P\n        XRKIlWnXtT4qNGZNTN0tR+NLG/6Bqd8OYBaFAUcue/w1VW6JQ2VGYZHnZu9S8LMc\n        FYBa5Ig9PxwGQOgq6RDKDbV+PqTQT5EFMeR1mrjckk4DQJjbxeMZbiNMG5kGECA8\n        g383P3elhn03WGbEEa4MNc3Z4+7c236QI3xWJfNPdUbXRaAwhy/6rTSFbzwKB0Jm\n        ebwzQfwjQY6f55MiI/RqDCyuPj3r3jyVRkK86pQKBAJwFHyqj9KaKXMZjfVnowLh\n        9svIGfNbGHpucATqREvUHuQbNnqkCx8VVhtYkhDb9fEP2xBu5VvHbR+3nfVhMut5\n        G34Ct5RS7Jt6LIfFdtcn8CaSas/l1HbiGeRgc70X/9aYx/V/CEJv0lIe8gP6uDoW\n        FPIZ7d6vH+Vro6xuWEGiuMaiznap2KhZmpkgfupyFmplh0s6knymuQINBFit2ioB\n        EADneL9S9m4vhU3blaRjVUUyJ7b/qTjcSylvCH5XUE6R2k+ckEZjfAMZPLpO+/tF\n        M2JIJMD4SifKuS3xck9KtZGCufGmcwiLQRzeHF7vJUKrLD5RTkNi23ydvWZgPjtx\n        Q+DTT1Zcn7BrQFY6FgnRoUVIxwtdw1bMY/89rsFgS5wwuMESd3Q2RYgb7EOFOpnu\n        w6da7WakWf4IhnF5nsNYGDVaIHzpiqCl+uTbf1epCjrOlIzkZ3Z3Yk5CM/TiFzPk\n        z2lLz89cpD8U+NtCsfagWWfjd2U3jDapgH+7nQnCEWpROtzaKHG6lA3pXdix5zG8\n        eRc6/0IbUSWvfjKxLLPfNeCS2pCL3IeEI5nothEEYdQH6szpLog79xB9dVnJyKJb\n        VfxXnseoYqVrRz2VVbUI5Blwm6B40E3eGVfUQWiux54DspyVMMk41Mx7QJ3iynIa\n        1N4ZAqVMAEruyXTRTxc9XW0tYhDMA/1GYvz0EmFpm8LzTHA6sFVtPm/ZlNCX6P1X\n        zJwrv7DSQKD6GGlBQUX+OeEJ8tTkkf8QTJSPUdh8P8YxDFS5EOGAvhhpMBYD42kQ\n        pqXjEC+XcycTvGI7impgv9PDY1RCC1zkBjKPa120rNhv/hkVk/YhuGoajoHyy4h7\n        ZQopdcMtpN2dgmhEegny9JCSwxfQmQ0zK0g7m6SHiKMwjwARAQABiQQ+BBgBCAAJ\n        BQJYrdoqAhsCAikJEI2BgDwOv82IwV0gBBkBCAAGBQJYrdoqAAoJEH6gqcPyc/zY\n        1WAP/2wJ+R0gE6qsce3rjaIz58PJmc8goKrir5hnElWhPgbq7cYIsW5qiFyLhkdp\n        YcMmhD9mRiPpQn6Ya2w3e3B8zfIVKipbMBnke/ytZ9M7qHmDCcjoiSmwEXN3wKYI\n        mD9VHONsl/CG1rU9Isw1jtB5g1YxuBA7M/m36XN6x2u+NtNMDB9P56yc4gfsZVES\n        KA9v+yY2/l45L8d/WUkUi0YXomn6hyBGI7JrBLq0CX37GEYP6O9rrKipfz73XfO7\n        JIGzOKZlljb/D9RX/g7nRbCn+3EtH7xnk+TK/50euEKw8SMUg147sJTcpQmv6UzZ\n        cM4JgL0HbHVCojV4C/plELwMddALOFeYQzTif6sMRPf+3DSj8frbInjChC3yOLy0\n        6br92KFom17EIj2CAcoeq7UPhi2oouYBwPxh5ytdehJkoo+sN7RIWua6P2WSmon5\n        U888cSylXC0+ADFdgLX9K2zrDVYUG1vo8CX0vzxFBaHwN6Px26fhIT1/hYUHQR1z\n        VfNDcyQmXqkOnZvvoMfz/Q0s9BhFJ/zU6AgQbIZE/hm1spsfgvtsD1frZfygXJ9f\n        irP+MSAI80xHSf91qSRZOj4Pl3ZJNbq4yYxv0b1pkMqeGdjdCYhLU+LZ4wbQmpCk\n        SVe2prlLureigXtmZfkqevRz7FrIZiu9ky8wnCAPwC7/zmS18rgP/17bOtL4/iIz\n        QhxAAoAMWVrGyJivSkjhSGx1uCojsWfsTAm11P7jsruIL61ZzMUVE2aM3Pmj5G+W\n        9AcZ58Em+1WsVnAXdUR//bMmhyr8wL/G1YO1V3JEJTRdxsSxdYa4deGBBY/Adpsw\n        24jxhOJR+lsJpqIUeb999+R8euDhRHG9eFO7DRu6weatUJ6suupoDTRWtr/4yGqe\n        dKxV3qQhNLSnaAzqW/1nA3iUB4k7kCaKZxhdhDbClf9P37qaRW467BLCVO/coL3y\n        Vm50dwdrNtKpMBh3ZpbB1uJvgi9mXtyBOMJ3v8RZeDzFiG8HdCtg9RvIt/AIFoHR\n        H3S+U79NT6i0KPzLImDfs8T7RlpyuMc4Ufs8ggyg9v3Ae6cN3eQyxcK3w0cbBwsh\n        /nQNfsA6uu+9H7NhbehBMhYnpNZyrHzCmzyXkauwRAqoCbGCNykTRwsur9gS41TQ\n        M8ssD1jFheOJf3hODnkKU+HKjvMROl1DK7zdmLdNzA1cvtZH/nCC9KPj1z8QC47S\n        xx+dTZSx4ONAhwbS/LN3PoKtn8LPjY9NP9uDWI+TWYquS2U+KHDrBDlsgozDbs/O\n        jCxcpDzNmXpWQHEtHU7649OXHP7UeNST1mCUCH5qdank0V1iejF6/CfTFU4MfcrG\n        YT90qFF93M3v01BbxP+EIY2/9tiIPbrd\n        =0YYh\n        -----END PGP PUBLIC KEY BLOCK-----\n\n  debconf_selections:\n    vhost:    dokku dokku/vhost_enable boolean true\n    # set the domain name of the new Dokku server\n    hostname: dokku dokku/hostname string $YOUR_FULL_QUALIFIED_DOMAIN\n    # this copies over the public SSH key assigned to the server\n    key:      dokku dokku/key_file string /home/ubuntu/.ssh/authorized_keys\n\npackages:\n    - dokku\npackage_update: true\npackage_upgrade: true\npackage_reboot_if_required: true\n</code></pre> <p>Shortly after running the create command you will get a confirmation that the instance has been created, and after about a minute it should be ready to login. Check the IP of the instance through the web UI or by running:</p> <pre><code>nova list\n</code></pre> <p>SSH with the <code>ubuntu</code> username and the public key previously added. Keep in mind that if you logged in quick enough Dokku might still be installing in the background, and not be ready. The installation takes a few minutes.</p>"},{"location":"getting-started/install/vagrant/","title":"Vagrant Installation Notes","text":"<ol> <li> <p>Download and install VirtualBox.</p> </li> <li> <p>Download and install Vagrant.</p> </li> <li> <p>Clone Dokku.</p> <pre><code>git clone https://github.com/dokku/dokku.git\n</code></pre> </li> <li> <p>Create VM.</p> <pre><code># Optional ENV arguments:\n# - `BOX_NAME`\n# - `BOX_URI`\n# - `BOX_MEMORY`\n# - `DOKKU_DOMAIN`\n# - `DOKKU_IP`\n# - `FORWARDED_PORT`.\ncd path/to/dokku\n\n# for most users\nvagrant up\n\n# windows users must instead use the following in an elevated command prompt\nvagrant up dokku-windows\n</code></pre> </li> <li> <p>Setup SSH Config in <code>~/.ssh/config</code>.</p> <pre><code>Host dokku.me\n    Port 22\n</code></pre> <p>For users that have customized the IP address of their VM - either in a custom <code>Vagrantfile</code> or via the <code>DOKKU_IP</code> environment variable - and are not using <code>10.0.0.2</code> for the Vagrant IP, you'll need to instead use the output of <code>vagrant ssh-config dokku</code> for your <code>~/.ssh/config</code> entry.</p> </li> <li> <p>Connect to the server via <code>vagrant ssh</code> and add your ssh key to the install. Additionally, set the global domain name to <code>dokku.me</code>.</p> <pre><code># usually your key is already available under the current user's `~/.ssh/authorized_keys` file\ncat ~/.ssh/authorized_keys | dokku ssh-keys:add admin\n\n# you can use any domain you already have access to\ndokku domains:set-global dokku.me\n</code></pre> <p>Please note, the <code>dokku.me</code> domain is setup to point to <code>10.0.0.2</code> along with all subdomains (i.e. <code>yourapp.dokku.me</code>). If you change the <code>DOKKU_IP</code> in your Vagrant setup you'll need to update your <code>/etc/hosts</code> file to point your reconfigured IP address.</p> </li> </ol> <p>You are now ready to deploy an app or install plugins.</p>"},{"location":"getting-started/installation/","title":"Getting Started with Dokku","text":""},{"location":"getting-started/installation/#what-is-dokku","title":"What is Dokku?","text":"<p>Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. Dokku supports building apps on the fly from a <code>git push</code> via either Dockerfile or by auto-detecting the language with Buildpacks, and then starts containers based on your built image. Using technologies such as nginx and cron, Web processes are automatically routed to, while background processes and automated cron tasks are also managed by Dokku.</p>"},{"location":"getting-started/installation/#system-requirements","title":"System Requirements","text":"<p>To start using Dokku, you'll need a system that meets the following minimum requirements:</p> <ul> <li>A fresh installation of any of the following operating systems:<ul> <li>Ubuntu 20.04/22.04</li> <li>Debian 10+ x64</li> </ul> </li> <li>A server with one of the following architectures<ul> <li>AMD64 (alternatively known as <code>x86_64</code>), commonly used for Intel cloud servers</li> <li>ARMV8 (alternatively known as <code>arm64</code>), commonly used for Raspberry PI and AWS Graviton</li> </ul> </li> </ul> <p>To avoid memory pressure during builds or runtime of your applications, we suggest the following:</p> <ul> <li>At least 1 GB of system memory<ul> <li>If your system has less than 1GB of memory, you can use this workaround.</li> </ul> </li> </ul> <p>Finally, we recommend attaching at least one domain name to your server. This is not required, but using a domain name will make app access easier. When connecting a domain, either a single domain or a wildcard may be associated to the server's IP.</p> <ul> <li>Wildcard domain (<code>*.domain.tld</code> A Record): will allow access to apps via <code>$APP.domain.tld</code>.</li> <li>Single domain (<code>domain.tld</code> A or CNAME Record): will result in apps being accessed via <code>domain.tld:$RANDOM_PORT</code>.</li> </ul> <p>Please see the dns documentation and domains documentation for more details.</p>"},{"location":"getting-started/installation/#installing-the-latest-stable-version","title":"Installing the latest stable version","text":"<p>This is the simple method of installing Dokku. For alternative methods of installation, see the advanced install guide.</p>"},{"location":"getting-started/installation/#1-install-dokku","title":"1. Install Dokku","text":"<p>To install the latest stable version of Dokku, you can run the following shell commands:</p> <pre><code># for debian systems, installs Dokku via apt-get\nwget -NP . https://dokku.com/install/v0.32.4/bootstrap.sh\nsudo DOKKU_TAG=v0.32.4 bash bootstrap.sh\n</code></pre> <p>The installation process takes about 5-10 minutes, depending upon internet connection speed.</p>"},{"location":"getting-started/installation/#2-setup-ssh-key-and-virtualhost-settings","title":"2. Setup SSH key and Virtualhost Settings","text":"<p>Once the installation is complete, you should configure an ssh key and set your global domain.</p> <pre><code># usually your key is already available under the current user's `~/.ssh/authorized_keys` file\ncat ~/.ssh/authorized_keys | dokku ssh-keys:add admin\n\n# you can use any domain you already have access to\n# this domain should have an A record or CNAME pointing at your server's IP\ndokku domains:set-global dokku.me\n\n# you can also use the ip of your server\ndokku domains:set-global 10.0.0.2\n\n# finally, you can use sslip.io to get subdomain support\n# as you would with a regular domain name\n# this would be done by appending `.sslip.io` to your ip address\ndokku domains:set-global 10.0.0.2.sslip.io\n</code></pre> <p>See the user management and domains documentation for more information.</p>"},{"location":"getting-started/installation/#3-deploy-your-first-application","title":"3. Deploy your first application","text":"<p>At this point, you should be able to deploy to the Dokku installation.</p>"},{"location":"getting-started/upgrading/","title":"Upgrading","text":"<p>If your version of Dokku is pre 0.3.0 (check with <code>dokku version</code>), we recommend a fresh install on a new server.</p>"},{"location":"getting-started/upgrading/#security-updates","title":"Security Updates","text":"<p>For any security related updates, please follow our Twitter account. As Dokku does not run any daemons, the security risk introduced by our software is minimal.</p> <p>Your operating system may occasionally provide security updates. We recommend setting unattended upgrades for your operating system. Here are some helpful links:</p> <ul> <li>Arch Linux System Maintenance</li> <li>Debian Unattended Upgrades</li> <li>Ubuntu Unattended Upgrades</li> </ul> <p>Docker releases updates periodically to their engine. We recommend reading their release notes and upgrading accordingly. Please see the Docker documentation for more details.</p>"},{"location":"getting-started/upgrading/#migration-guides","title":"Migration Guides","text":"<p>Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.</p> <ul> <li>Upgrading to 0.32</li> <li>Upgrading to 0.31</li> <li>Upgrading to 0.30</li> <li>Upgrading to 0.29</li> <li>Upgrading to 0.28</li> <li>Upgrading to 0.27</li> <li>Upgrading to 0.26</li> <li>Upgrading to 0.25</li> <li>Upgrading to 0.24</li> <li>Upgrading to 0.23</li> <li>Upgrading to 0.22</li> <li>Upgrading to 0.21</li> <li>Upgrading to 0.20</li> <li>Upgrading to 0.10</li> <li>Upgrading to 0.9</li> <li>Upgrading to 0.8</li> <li>Upgrading to 0.7</li> <li>Upgrading to 0.6</li> <li>Upgrading to 0.5</li> </ul>"},{"location":"getting-started/upgrading/#before-upgrading","title":"Before upgrading","text":"<p>If you'll be updating docker or the herokuish package simultaneously, it's recommended that you stop all applications before upgrading and rebuild afterwards. This is not required if the upgrade only impacts the <code>dokku</code> package.</p> <p>Why do we recommend stopping all apps?</p> <ul> <li><code>docker</code>: Containers may be randomly reset during the upgrade process, resulting in   requests being sent to the wrong containers. Acknowledging and scheduling downtime   thus becomes much more important.</li> <li><code>herokuish</code>: While not required, it may be useful to take advantage of the latest   base image. Herokuish changes do not cause issues unless the base OS changes, which   may happen in minor or major releases.</li> </ul> <pre><code># for 0.22.0 and newer versions, use\ndokku ps:stop --all\n\n# for versions between 0.11.4 and 0.21.4, use\ndokku ps:stopall\n\n# for versions between 0.8.1 and 0.11.3, use\ndokku --quiet apps:list | xargs -L1 dokku ps:stop\n\n# for versions older than 0.8.1, use\ndokku --quiet apps | xargs -L1 dokku ps:stop\n</code></pre>"},{"location":"getting-started/upgrading/#after-upgrading","title":"After upgrading","text":"<p>After upgrading, you should rebuild the applications to take advantage of any new buildpacks that were released:</p> <pre><code>dokku ps:rebuild --all\n</code></pre>"},{"location":"getting-started/upgrading/#upgrading-using-dokku-update","title":"Upgrading using <code>dokku-update</code>","text":"<p>We provide a helpful binary called <code>dokku-update</code>. This is a recommended package that:</p> <ul> <li>Can be installed separately, so upgrading Dokku will not affect the running of this package.</li> <li>Automates many of the upgrade instructions for you.</li> <li>Provides a clean way for us to further enhance the upgrade process in the future.</li> </ul> <p>This binary is available on Debian and RPM-based systems from our package repositories under the name <code>dokku-update</code>. When installing from source, this is available from a separate Github repository at dokku/dokku-update.</p>"},{"location":"getting-started/upgrading/#upgrading-using-apt","title":"Upgrading using <code>apt</code>","text":"<p>If Dokku was installed in a Debian or Ubuntu system, via <code>apt-get install dokku</code> or <code>bootstrap.sh</code>, you can upgrade with <code>apt-get</code>:</p> <pre><code># update your local apt cache\nsudo apt-get update -qq\n\n# update dokku and its dependencies\nsudo apt-get -qq -y --no-install-recommends install dokku herokuish sshcommand plugn gliderlabs-sigil dokku-update dokku-event-listener\n\n# or just upgrade every package:\nsudo apt-get upgrade\n</code></pre>"},{"location":"getting-started/upgrading/#upgrading-from-source","title":"Upgrading from source","text":"<p>If you installed Dokku from source (less common), upgrade with:</p> <pre><code>cd ~/dokku\ngit pull --tags origin master\n\n# continue to install from source\nsudo DOKKU_BRANCH=master make install\n\n# upgrade to debian package-based installation\nsudo make install\n</code></pre> <p>To upgrade Herokuish from source, upgrade with:</p> <pre><code>cd /tmp\ngit clone https://github.com/gliderlabs/herokuish.git\ncd herokuish\nCIRCLECI=true IMAGE_NAME=gliderlabs/herokuish BUILD_TAG=latest make build/docker\n</code></pre>"},{"location":"networking/dns/","title":"DNS Configuration","text":"<p>Note</p> <p>This is a work in progress.</p>"},{"location":"networking/dns/#dns-versions","title":"DNS Versions","text":"<p>There are many different DNS servers 'in the wild'.  Some of the popular ones on Linux are BIND, dnsmasq, and pdns.  Windows has its own built-in DNS server as well as Unbound, Posadis, and more.  A full list of DNS packages can be found on Wikipedia under Comparison of DNS Server Software.  In addition to the various DNS packages, there are tens of thousands of Managed DNS Providers out that all have different DNS interfaces.</p>"},{"location":"networking/dns/#focus","title":"Focus","text":"<p>Because there are so many different DNS server packages out there as well as a tremendous number of Managed DNS Providers, we will focus on the concepts of DNS as well as providing examples in the 'BIND' format so you can adapt the information to your own server package or managed DNS provider.</p>"},{"location":"networking/dns/#assumptions","title":"Assumptions","text":"<ul> <li>We assume you have a passing familiarity with DNS.  If not, you can read an in-depth article on DNS.  But basically you need to know that DNS changes names (like example.tld) into addresses (like 127.0.0.1)</li> <li>We assume you already have a domain name registered and pointed to your favorite Managed DNS Provider or have your own BIND DNS server running.</li> <li>You have a server on the internet and are about to follow the instructions in the README to get Dokku installed.  Don't do the install just yet though.</li> </ul>"},{"location":"networking/dns/#caching","title":"Caching","text":"<p>Please remember that DNS relies heavily on caching.  Changes you make to DNS could take anywhere from a few seconds to a few days to propagate.  If you tried surfing to example.tld, then changed the IP address in DNS, it could be a while before your computer picks up on the changes.</p>"},{"location":"networking/dns/#getting-started","title":"Getting started","text":"<p>For the examples, we will use the domain name <code>example.tld</code> and the IP address <code>127.0.0.1</code>.</p> <p>Dokku uses DNS to differentiate between apps on your dokku-powered server.  If you are using the domain <code>example.tld</code>, and you have two apps <code>node-js-app1</code> and <code>node-js-app2</code>, Dokku will make them available at <code>node-js-app1.example.tld</code> and <code>node-js-app2.example.tld</code>.</p> <p>To get started, you need to know the IP address of your Dokku server.  Connect to it and run <code>ifconfig</code> or <code>ip addr</code> to see the IP address.</p> <p>Now you have to make a decision about your domain.  Do you want everything and anything at <code>example.tld</code> to go to your Dokku server, or would you rather use a 'sub domain' for your Dokku server?</p> <p>In other words, do you want your applications on your Dokku server accessible via <code>node-js-app.example.tld</code> or via <code>node-js-app.myserver.example.tld</code>?</p>"},{"location":"networking/dns/#using-a-sub-domain-node-js-appmyserverexampletld","title":"Using a sub-domain (node-js-app.myserver.example.tld)","text":"<p>Using a sub-domain is easy.  When you set up your server, you probably gave it a name like <code>myserver.example.tld</code>.</p> <p>Go in to your Managed DNS provider and create an <code>A</code> record named <code>myserver</code> and put in the IP address you got from your server a few moments ago.</p> <p>Hopefully your managed DNS provider also supports wildcards.  Create a second <code>A</code> record named <code>*.myserver</code> along with the IP address you got from your server a few moments ago.</p> <p>If you are using BIND, your zone file will look similar to this:</p> <pre><code>$ORIGIN example.tld\n$TTL 5m\n\nmyserver         IN      A       127.0.0.1\n*.myserver       IN      A       127.0.0.1\n</code></pre> <p>You can verify your changes in Linux by trying one or more of the following commands:</p> <ul> <li><code>host myserver.example.tld</code></li> <li><code>dig -t A myserver.example.tld</code></li> <li><code>nslookup myserver.example.tld</code></li> </ul> <p>Now is a good time to remind you that the answers you get MAY BE CACHED.</p> <p>If everything is working correctly, you should also be able to query for any other name under <code>myserver.example.tld</code> and get back the IP address of your server.  Try:</p> <ul> <li><code>host test.myserver.example.tld</code></li> <li><code>host xyzzy.myserver.example.tld</code></li> </ul> <p>If they all return your IP address, you have set DNS up properly for dokku.  You should also be able to <code>ssh root@myserver.example.tld</code> and access your server.</p> <p>Proceed with the setup instructions in the installation documentation</p>"},{"location":"networking/dns/#using-the-root-of-your-domain-node-js-appexampletld","title":"Using the root of your domain (node-js-app.example.tld)","text":"<p>This section is a work in progress.  It is incomplete.</p> <p>Using the 'root' of your domain is nearly identical to the previous example.</p> <ul> <li>hostname is under <code>example.tld</code>, still needs <code>A</code> record.</li> <li>Update your global domain using the domains plugin.</li> </ul>"},{"location":"networking/network/","title":"Network Management","text":"<p>New</p> <p>Introduced in 0.11.0, Enhanced in 0.20.0</p> <pre><code>network:create &lt;network&gt;                 # Creates an attachable docker network\nnetwork:destroy &lt;network&gt;                # Destroys a docker network\nnetwork:exists &lt;network&gt;                 # Checks if a docker network exists\nnetwork:info &lt;network&gt;                   # Outputs information about a docker network\nnetwork:list                             # Lists all docker networks\nnetwork:report [&lt;app&gt;] [&lt;flag&gt;]          # Displays a network report for one or more apps\nnetwork:rebuild &lt;app&gt;                    # Rebuilds network settings for an app\nnetwork:rebuildall                       # Rebuild network settings for all apps\nnetwork:set &lt;app&gt; &lt;key&gt; (&lt;value&gt;)        # Set or clear a network property for an app\n</code></pre> <p>The Network plugin allows developers to abstract the concept of container network management, allowing developers to both change what networks a given container is attached to as well as rebuild the configuration on the fly.</p>"},{"location":"networking/network/#usage","title":"Usage","text":""},{"location":"networking/network/#listing-networks","title":"Listing networks","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>You can easily list all available networks using the <code>network:list</code> command:</p> ShellOutput <pre><code>dokku network:list\n</code></pre> <pre><code>=====&gt; Networks\nbridge\nhost\nnone\ntest-network\n</code></pre> <p>Note that you can easily hide extra output from Dokku commands by using the <code>--quiet</code> flag, which makes it easier to parse on the command line.</p> ShellOutput <pre><code>dokku --quiet network:list\n</code></pre> <pre><code>bridge\nhost\nnone\ntest-network\n</code></pre>"},{"location":"networking/network/#creating-a-network","title":"Creating a network","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>Docker networks can be created via the <code>network:create</code> command. Executing this command will create an attachable <code>bridge</code> network. This can be used to route requests between containers without going through any public network.</p> ShellOutput <pre><code>dokku network:create test-network\n</code></pre> <pre><code>-----&gt; Creating network test-network\n</code></pre> <p>Specifying other additional flags or other types of networks can be created directly via the <code>docker</code> command.</p>"},{"location":"networking/network/#destroying-a-network","title":"Destroying a network","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>A Docker network without any associated containers may be destroyed via the <code>network:destroy</code> command. Docker will refuse to destroy networks that have containers attached.</p> ShellOutput <pre><code>dokku network:destroy test-network\n</code></pre> <pre><code> !     WARNING: Potentially Destructive Action\n !     This command will destroy network test.\n !     To proceed, type \"test\"\n-----&gt; Destroying network test\n</code></pre> <p>Info</p> <p>test</p> <p>As the command is destructive, it will default to asking for confirmation before executing the removal of the network. This may be avoided by providing the <code>--force</code> flag:</p> ShellOutput <pre><code>dokku --force network:destroy test-network\n</code></pre> <pre><code>-----&gt; Destroying network test\n</code></pre>"},{"location":"networking/network/#checking-if-a-network-exists","title":"Checking if a network exists","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the <code>network:exists</code> command:</p> ShellOutput <pre><code>dokku network:exists nonexistent-network\n</code></pre> <pre><code>Network does not exist\n</code></pre> <p>The <code>network:exists</code> command will return non-zero if the network does not exist, and zero if it does.</p>"},{"location":"networking/network/#checking-network-info","title":"Checking network info","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>Network information can be retrieved via the <code>network:info</code> command. This is a slightly different version of the <code>docker network</code> command.</p> ShellOutput <pre><code>dokku network:info test-network\n</code></pre> <pre><code>// TODO\n</code></pre>"},{"location":"networking/network/#routing-an-app-to-a-known-ipport-combination","title":"Routing an app to a known ip:port combination","text":"<p>In some cases, it may be necessary to route an app to an existing <code>$IP:$PORT</code> combination. This is particularly the case for internal admin tools or services that aren't run by Dokku but have a web ui that would benefit from being exposed by Dokku. This can be done by using a proxy application and routing requests through that.</p> <pre><code># for a service listening on:\n# - ip address: 127.0.0.1\n# - port: 8080\n\n# create the app\ndokku apps:create local-app\n\n# add an extra host that maps host.docker.internal to the docker gateway\ndokku docker-options:add local-app deploy \"--add-host=host.docker.internal:host-gateway\"\n\n# set the SERVICE_HOST to the mapped hostname\ndokku config:set local-app SERVICE_HOST=host.docker.internal\n\n# set the SERVICE_PORT to the port combination for your app\ndokku config:set local-app SERVICE_PORT=8080\n\n# set the domains desired\ndokku domains:set local-app local-app.dokku.me\n\n# deploy the service-proxy image\ndokku git:from-image local-app dokku/service-proxy:latest\n</code></pre> <p>Only a single <code>$IP:$PORT</code> combination can be routed to for a given app, and that <code>$IP:$PORT</code> combination must be accessible to the service proxy on initial deploy, or the service proxy won't start.</p>"},{"location":"networking/network/#attaching-an-app-to-a-network","title":"Attaching an app to a network","text":"<p>New</p> <p>Introduced in 0.20.0, Requires Docker 1.21+</p> <p>Apps will default to being associated with the default <code>bridge</code> network or a network specified by the <code>initial-network</code> network property. Additionally, an app can be attached to <code>attachable</code> networks by changing the <code>attach-post-create</code> or <code>attach-post-deploy</code> network properties when using the docker-local scheduler. A change in these values will require an app deploy or rebuild.</p> <pre><code># associates the network after a container is created but before it is started\n# commonly used for cross-app networking\ndokku network:set node-js-app attach-post-create test-network\n\n# associates the network after the deploy is successful but before the proxy is updated\n# used for cross-app networking when healthchecks must be invoked first\ndokku network:set node-js-app attach-post-deploy other-test-network\n\n# associates the network at container creation\n# typically blocks access to services and external routing\ndokku network:set node-js-app initial-network global-network\n</code></pre> <p>Multiple networks can also be specified for the <code>attach-post-create</code> and <code>attach-post-deploy</code> phases.</p> <pre><code># one or more networks can be specified\ndokku network:set node-js-app attach-post-create test-network test-network-2\n</code></pre> <p>Setting the <code>attach</code> network property to an empty value will de-associate the container with the network.</p> <pre><code>dokku network:set node-js-app attach-post-create\ndokku network:set node-js-app attach-post-deploy\ndokku network:set node-js-app initial-network\n</code></pre> <p>The network properties can also be set globally. The global default value is an empty string, and the global value is used when no app-specific value is set.</p> <pre><code>dokku network:set --global attach-post-create global-create-network\ndokku network:set --global attach-post-deploy global-deploy-network\ndokku network:set --global initial-network global-network\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku network:set --global attach-post-create\ndokku network:set --global attach-post-deploy\ndokku network:set --global initial-network\n</code></pre>"},{"location":"networking/network/#network-aliases","title":"Network Aliases","text":"<p>Note</p> <p>This feature is only available when an app has been attached to a network other than the default <code>bridge</code> network.</p> <p>When a container created for a deployment is being attached to a network - regardless of which network property was used - a network alias of the pattern <code>APP.PROC_TYPE</code> will be added to all containers. This can be used to load-balance requests between containers. For an application named <code>node-js-app</code> with a process type of web, the network alias - or resolvable DNS record within the network - will be:</p> <pre><code>node-js-app.web\n</code></pre> <p>The fully-qualified URL for the resource will depend upon the <code>PORT</code> being listened to by the application. Applications built via buildpacks will have their <code>PORT</code> environment variable set to <code>5000</code>, and as such internal network requests for the above example should point to the following:</p> <pre><code>http://node-js-app.web:5000\n</code></pre> <p>Dockerfile-based applications may listen on other ports. For more information on how ports are specified for applications, please refer to the port management documentation.</p>"},{"location":"networking/network/#specifying-a-custom-tld","title":"Specifying a custom TLD","text":"<p>When attaching applications to networks, a custom TLD can be specified via the <code>network:set</code> command. This TLD is suffixed to the network alias for the application/process-type combination for all networks to which the application is attached, and cannot be customized per network. The default value is an empty string.</p> <p>To specify a TLD of <code>svc.cluster.local</code> for your application, run the following command:</p> <pre><code># replace node-js-app with your application name\ndokku network:set node-js-app tld svc.cluster.local\n</code></pre> <p>With an application named <code>node-js-app</code> and a process-type named <code>web</code>, the above command will turn the network alias into:</p> <pre><code>node-js-app.web.svc.cluster.local\n</code></pre> <p>Note that this has no impact on container port handling, and users must still specify the container port when making internal network requests.</p> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku network:set node-js-app tld\n</code></pre> <p>The <code>tld</code> property can also be set globally. The global default is emty string, and the global value is used when no app-specific value is set.</p> <pre><code>dokku network:set --global tld svc.cluster.local\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku network:set --global tld\n</code></pre>"},{"location":"networking/network/#when-to-attach-containers-to-a-network","title":"When to attach containers to a network","text":"<p>Containers can be attached to a network for a variety of reasons:</p> <ul> <li>A background process in one app needs to communicate to a webservice in another app</li> <li>An app needs to talk to a container not managed by Dokku in a secure manner</li> <li>A custom network that allows transparent access to another host exists and is necessary for an app to run</li> </ul> <p>Whatever the reason, the semantics of the two network hooks are important and are outlined before.</p> <ul> <li><code>attach-post-create</code>:<ul> <li>Phase it applies to:<ul> <li><code>build</code>: Intermediate containers created during the build process.</li> <li><code>deploy</code>: Deployed app containers.</li> <li><code>run</code>: Containers created by the <code>run</code> command.</li> </ul> </li> <li>Container state on attach: <code>created</code> but not <code>running</code></li> <li>Use case: When the container needs to access a resource on the network.</li> <li>Example: The app needs to talk to a database on the same network when it first boots.</li> </ul> </li> <li><code>attach-post-deploy</code><ul> <li>Phase it applies to:<ul> <li><code>deploy</code>: Deployed app containers.</li> </ul> </li> <li>Container state on attach: <code>running</code></li> <li>Use case: When another container on the network needs to access this container.</li> <li>Example: A background process needs to communicate with the web process exposed by this container.</li> </ul> </li> <li><code>initial-network</code>:<ul> <li>Phase it applies to:<ul> <li><code>build</code>: Intermediate containers created during the build process.</li> <li><code>deploy</code>: Deployed app containers.</li> <li><code>run</code>: Containers created by the <code>run</code> command.</li> </ul> </li> <li>Container state on attach: <code>created</code></li> <li>Use case: When another container on the network is already running and needed by this container.</li> <li>Example: A key-value store exposing itself to all your apps may be on the <code>initial-network</code>.</li> </ul> </li> </ul> <p>Warning</p> <p>If the attachment fails during the <code>running</code> container state, this may result in your application failing to respond to proxied requests once older containers are removed.</p>"},{"location":"networking/network/#rebuilding-network-settings","title":"Rebuilding network settings","text":"<p>There are cases where you may need to rebuild the network configuration for an app, such as on app boot or container restart. In these cases, you can use the <code>network:rebuild</code> command:</p> <pre><code>dokku network:rebuild node-js-app\n</code></pre> <p>Info</p> <p>This command will exit a non-zero number that depends on the number of containers for which configuration could not be built</p>"},{"location":"networking/network/#rebuilding-all-network-settings","title":"Rebuilding all network settings","text":"<p>In some cases, a docker upgrade may reset container IPs or Ports. In both cases, you can quickly rewrite those files by using the <code>network:rebuildall</code> command:</p> <pre><code>dokku network:rebuildall\n</code></pre> <p>Info</p> <p>This command will exit a non-zero number that depends on the number of containers for which configuration could not be built</p>"},{"location":"networking/network/#container-network-interface-binding","title":"Container network interface binding","text":"<p>Info</p> <p>This functionality does not control the <code>--network</code> docker flag. Please use the docker-options plugin to manage this flag.</p> <p>By default, an app will only bind to the internal interface. This behavior can be modified per app by changing the <code>bind-all-interfaces</code> network property.</p> <pre><code># bind to the default docker interface (`docker0`) with a random internal ip\n# this is the default behavior\ndokku network:set node-js-app bind-all-interfaces false\n\n# bind to all interfaces (`0.0.0.0`) on a random port for each upstream port\n# this will make the app container directly accessible by other hosts on your network\n# ports are randomized for every deploy, e.g. `0.0.0.0:32771-&gt;5000/tcp`.\ndokku network:set node-js-app bind-all-interfaces true\n</code></pre> <p>By way of example, in the default case, each container is bound to the docker interface:</p> ShellOutput <pre><code>docker ps\n</code></pre> <pre><code>CONTAINER ID        IMAGE                      COMMAND                CREATED              STATUS              PORTS               NAMES\n1b88d8aec3d1        dokku/node-js-app:latest   \"/bin/bash -c '/star   About a minute ago   Up About a minute                       node-js-app.web.1\n</code></pre> <p>As such, the container's IP address will be an internal IP, and thus it is only accessible on the host itself:</p> ShellOutput <pre><code>docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' node-js-app.web.1\n</code></pre> <pre><code>172.17.0.6\n</code></pre> <p>However, you can disable the internal proxying via the <code>network:set</code> command so that it will listen on the host's IP address:</p> ShellOutput <pre><code>dokku network:set node-js-app bind-all-interfaces true\n\n# container bound to all interfaces\ndocker ps\n</code></pre> <pre><code>CONTAINER ID        IMAGE                      COMMAND                CREATED              STATUS              PORTS                     NAMES\nd6499edb0edb        dokku/node-js-app:latest   \"/bin/bash -c '/star   About a minute ago   Up About a minute   0.0.0.0:49153-&gt;5000/tcp   node-js-app.web.1\n</code></pre> <p>The <code>bind-all-interfaces</code> property can also be set globally. The global default is <code>false</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku network:set --global bind-all-interfaces true\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku network:set --global bind-all-interfaces\n</code></pre>"},{"location":"networking/network/#displaying-network-reports-for-an-app","title":"Displaying network reports for an app","text":"<p>You can get a report about the app's network status using the <code>network:report</code> command:</p> ShellOutput <pre><code>dokku network:report\n</code></pre> <pre><code>=====&gt; node-js-app network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners: 172.17.0.1:5000\n=====&gt; python-sample network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners:          172.17.0.2:5000\n=====&gt; ruby-sample network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners:\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku network:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app network information\n       Network attach post create:\n       Network attach post deploy:\n       Network bind all interfaces:   false\n       Network computed attach post create:\n       Network computed attach post deploy:\n       Network computed bind all interfaces:false\n       Network computed initial network:\n       Network computed tld:\n       Network global attach post create:\n       Network global attach post deploy:\n       Network global bind all interfaces:false\n       Network global initial network:\n       Network global tld:\n       Network initial network:\n       Network tld:\n       Network web listeners: 172.17.0.1:5000\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku network:report node-js-app --network-bind-all-interfaces\n</code></pre>"},{"location":"networking/port-management/","title":"Port Management","text":"<p>New</p> <p>Introduced in 0.31.0, replaces the previous <code>proxy:ports*</code> commands</p> <pre><code>ports:list &lt;app&gt;                        # List port mappings for an app\nports:add &lt;app&gt; &lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt; [&lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt;...]           # Add port mappings to an app\nports:clear &lt;app&gt;                       # Clear all port mappings for an app\nports:remove &lt;app&gt; &lt;host-port&gt; [&lt;host-port&gt;|&lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt;...]                      # Remove specific port mappings from an app\nports:set &lt;app&gt; &lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt; [&lt;scheme&gt;:&lt;host-port&gt;:&lt;container-port&gt;...]           # Set port mappings for an app\n</code></pre>"},{"location":"networking/port-management/#usage","title":"Usage","text":"<p>Warning</p> <p>Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable.</p> <p>Users should also avoid setting the <code>PORT</code> environment variable. Dokku will use port mappings to set this value. Overriding this manually may cause issues in application routing.</p> <p>You can now configure <code>host -&gt; container</code> port mappings with the <code>ports:*</code> commands. This mapping is currently supported by the built-in nginx-vhosts plugin.</p> <p>By default, buildpack apps and dockerfile apps without explicitly exposed ports (i.e. using the <code>EXPOSE</code> directive) will be configured with a listener on port <code>80</code> (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port <code>5000</code>. Dockerfile apps with explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.</p> <p>Note</p> <p>This default behavior will not be automatically changed on subsequent pushes and must be manipulated with the <code>ports:*</code> commands detailed below.</p>"},{"location":"networking/port-management/#port-scheme","title":"Port Scheme","text":"<p>The proxy port scheme is as follows:</p> <ul> <li><code>SCHEME:HOST_PORT:CONTAINER_PORT</code></li> </ul> <p>The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in <code>nginx-vhosts</code> proxy implementation supports the <code>http</code>, <code>https</code>, <code>grpc</code> and <code>grpcs</code> schemes. For the <code>grpc</code> and <code>grpcs</code> see nginx blog post on grpc.</p> <p>Developers of proxy implementations are encouraged to use whatever schemes make the most sense, and ignore configurations which they do not support. For instance, a <code>udp</code> proxy implementation can safely ignore <code>http</code> and <code>https</code> port mappings.</p> <p>To change the proxy implementation in use for an application, use the <code>proxy:set</code> command:</p> <pre><code># no validation will be performed against\n# the specified proxy implementation\ndokku proxy:set node-js-app nginx\n</code></pre>"},{"location":"networking/port-management/#listing-port-mappings","title":"Listing port mappings","text":"<p>To inspect the port mapping for a given application, use the <code>ports:list</code> command:</p> ShellOutput <pre><code>dokku ports:list node-js-app\n</code></pre> <pre><code>-----&gt; Port mappings for node-js-app\n-----&gt; scheme             host port                 container port\nhttp                      80                        5000\n</code></pre> <p>The above application is listening on the host's port <code>80</code>, which we can test via curl:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me\n</code></pre> <pre><code>Hello World!\n</code></pre>"},{"location":"networking/port-management/#adding-a-custom-port-mapping","title":"Adding a custom port mapping","text":"<p>There are cases where we may wish for the service to be listening on more than one port, such as port 8080. Normally, this would not be possible:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me:8080\n</code></pre> <pre><code>curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused\n</code></pre> <p>However, we can use the <code>ports:add</code> command to add a second external port mapping - <code>8080</code> - to our application's port <code>5000</code>.</p> ShellOutput <pre><code>dokku ports:add node-js-app http:8080:5000\n</code></pre> <pre><code>-----&gt; Configuring node-js-app.dokku.me...(using built-in template)\n-----&gt; Creating http nginx.conf\n       Reloading nginx\n</code></pre> <p>We can now test that port 80 still responds properly:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me\n</code></pre> <pre><code>Hello World!\n</code></pre> <p>And our new listening port of <code>8080</code> also works:</p> ShellOutput <pre><code>curl http://node-js-app.dokku.me:8080\n</code></pre> <pre><code>Hello World!\n</code></pre>"},{"location":"networking/port-management/#setting-all-port-mappings-at-once","title":"Setting all port mappings at once","text":"<p>Port mappings can also be force set using the <code>ports:set</code> command.</p> ShellOutput <pre><code>dokku ports:set node-js-app http:8080:5000\n</code></pre> <pre><code>-----&gt; Configuring node-js-app.dokku.me...(using built-in template)\n-----&gt; Creating http nginx.conf\n       Reloading nginx\n</code></pre>"},{"location":"networking/port-management/#removing-a-port-mapping","title":"Removing a port mapping","text":"<p>A port mapping can be removed using the <code>ports:remove</code> command if it no longer necessary:</p> <pre><code>dokku ports:remove node-js-app http:80:5000\n</code></pre> <p>Ports may also be removed by specifying only the <code>host-port</code> value. This effectively acts as a wildcard and removes all mappings for that particular host port.</p> <pre><code>dokku ports:remove node-js-app http:80\n</code></pre>"},{"location":"networking/port-management/#port-management-by-deployment-method","title":"Port management by Deployment Method","text":"<p>Warning</p> <p>If you set a port map but do not have a global domain set, Dokku will reset that map upon first deployment.</p>"},{"location":"networking/port-management/#buildpacks","title":"Buildpacks","text":"<p>For buildpack deployments, your application must respect the <code>PORT</code> environment variable. We will typically set this to port <code>5000</code>, but this is not guaranteed. If you do not respect the <code>PORT</code> environment variable, your containers may start but your services will not be accessible outside of that container.</p>"},{"location":"networking/port-management/#dockerfile","title":"Dockerfile","text":"<p>Info</p> <p>Changed as of 0.5.0</p> <p>Dokku's default proxy implementation - nginx - supports HTTP and GRPC request proxying. At this time, we do not support proxying plain TCP or UDP ports. UDP ports can be exposed by disabling the nginx proxy with <code>dokku proxy:disable myapp</code> and manually exposing the ports via the <code>docker-options</code> plugin. For example, <code>dokku docker-options:add myapp deploy \"-p 2456:2456/udp\"</code>. If you would like to investigate alternative proxy methods, please refer to our proxy management documentation.</p>"},{"location":"networking/port-management/#applications-using-expose","title":"Applications using EXPOSE","text":"<p>Dokku will extract all tcp ports exposed using the <code>EXPOSE</code> directive (one port per line) and setup nginx to proxy the same port numbers to listen publicly. If you would like to change the exposed port, you should do so within your <code>Dockerfile</code>.</p> <p>For example, if the Dokku installation is configured with the domain <code>dokku.me</code> and an application named <code>node-js-app</code> is deployed with following Dockerfile:</p> <pre><code>FROM ubuntu:20.04\nEXPOSE 1234\nRUN python -m SimpleHTTPServer 1234\n</code></pre> <p>The application would be exposed to the user at <code>node-js-app.dokku.me:1234</code>. If this is not desired, the following application configuration may be applied:</p> <pre><code># add a port mapping to port 80\ndokku ports:add node-js-app http:80:1234\n\n# remove the incorrect port mapping\ndokku ports:remove node-js-app http:1234:1234\n</code></pre>"},{"location":"networking/port-management/#applications-not-using-expose","title":"Applications not using EXPOSE","text":"<p>Any application that does not use an <code>EXPOSE</code> directive will result in Dokku defaulting to port <code>5000</code>. This behavior mimics the behavior of a Buildpack deploy. If your application does not support the <code>PORT</code> environment variable, then you will either need to:</p> <ul> <li>modify your application to support the <code>PORT</code> environment variable.</li> <li>switch to using an <code>EXPOSE</code> directive in your Dockerfile.</li> </ul>"},{"location":"networking/port-management/#displaying-ports-reports-for-an-app","title":"Displaying ports reports for an app","text":"<p>You can get a report about the app's ports status using the <code>ports:report</code> command:</p> ShellOutput <pre><code>dokku ports:report\n</code></pre> <pre><code>=====&gt; node-js-app ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000 https:443:5000\n=====&gt; python-sample ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000\n=====&gt; ruby-sample ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku ports:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app ports information\n       Port map detected: http:80:5000\n       Port map:          http:80:5000 https:443:5000\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku ports:report node-js-app --ports-map\n</code></pre>"},{"location":"networking/proxy-management/","title":"Proxy Management","text":"<p>New</p> <p>Introduced in 0.5.0, Enhanced in 0.6.0</p> <pre><code>proxy:build-config [--parallel count] [--all|&lt;app&gt;] # (Re)builds config for given app\nproxy:clear-config [--all|&lt;app&gt;] # Clears config for given app\nproxy:disable [--parallel count] [--all|&lt;app&gt;]      # Disable proxy for app\nproxy:enable [--parallel count] [--all|&lt;app&gt;]       # Enable proxy for app\nproxy:report [&lt;app&gt;] [&lt;flag&gt;]                       # Displays a proxy report for one or more apps\nproxy:set [&lt;app&gt;|--global] &lt;proxy-type&gt;                        # Set proxy type for app\n</code></pre> <p>In Dokku 0.5.0, port proxying was decoupled from the <code>nginx-vhosts</code> plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. In the future this will allow other proxy software - such as HAProxy or Caddy - to be used in place of nginx.</p>"},{"location":"networking/proxy-management/#usage","title":"Usage","text":""},{"location":"networking/proxy-management/#changing-the-proxy","title":"Changing the proxy","text":"<p>The default proxy shipped with Dokku is <code>nginx</code>. It can be changed via the <code>proxy:set</code> command.</p> ShellOutput <pre><code>dokku proxy:set node-js-app caddy\n</code></pre> <pre><code>-----&gt; Setting config vars\n       DOKKU_APP_PROXY_TYPE:  caddy\n</code></pre> <p>The proxy may also be set on a global basis. This is usually preferred as running multiple proxy implementations may cause port collision issues.</p> ShellOutput <pre><code>dokku proxy:set --global caddy\n</code></pre> <pre><code>-----&gt; Setting config vars\n       DOKKU_PROXY_TYPE:  caddy\n</code></pre> <p>Changing the proxy does not stop or start any given proxy implementation. Please see the documentation for your proxy implementation for details on how to perform a change.</p>"},{"location":"networking/proxy-management/#regenerating-proxy-config","title":"Regenerating proxy config","text":"<p>In certain cases, your app proxy configs may drift from the correct config for your app. You may regenerate the config at any point via the <code>proxy:build-config</code> command. This command will trigger a rebuild for the configured proxy implementation (default: nginx) for a given app. The command may fail if there are no current web listeners for your app.</p> <pre><code>dokku proxy:build-config node-js-app\n</code></pre> <p>All apps may have their proxy config rebuilt by using the <code>--all</code> flag.</p> <pre><code>dokku proxy:build-config --all\n</code></pre> <p>By default, rebuilding proxy configs for all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku proxy:build-config --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku proxy:build-config --all --parallel -1\n</code></pre>"},{"location":"networking/proxy-management/#clearing-the-generated-proxy-config","title":"Clearing the generated proxy config","text":"<p>New</p> <p>Introduced in 0.27.0</p> <p>Generated proxy configurations can also be cleared using the <code>proxy:clear-config</code> command.</p> <pre><code>dokku proxy:clear-config node-js-app\n</code></pre> <p>All apps may have their proxy config cleared by using the <code>--all</code> flag.</p> <pre><code>dokku proxy:clear-config --all\n</code></pre> <p>Clearing a proxy configuration has different effects depending on the proxy plugin in use. Consul the documentation for your proxy implementation for further details.</p>"},{"location":"networking/proxy-management/#displaying-proxy-reports-for-an-app","title":"Displaying proxy reports for an app","text":"<p>New</p> <p>Introduced in 0.8.1</p> <p>You can get a report about the app's proxy status using the <code>proxy:report</code> command:</p> ShellOutput <pre><code>dokku proxy:report\n</code></pre> <pre><code>=====&gt; node-js-app proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n=====&gt; python-sample proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n=====&gt; ruby-sample proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku proxy:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app proxy information\n       Proxy enabled:       true\n       Proxy type:          nginx\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku proxy:report node-js-app --proxy-type\n</code></pre>"},{"location":"networking/proxy-management/#proxy-port-scheme","title":"Proxy Port Scheme","text":"<p>See the port scheme documentation for more information on the port mapping scheme used by dokku.</p>"},{"location":"networking/proxy-management/#proxy-port-mapping","title":"Proxy port mapping","text":"<p>See the port management documentation for more information on how port mappings are managed for an application.</p>"},{"location":"networking/proxy-management/#container-network-interface-binding","title":"Container network interface binding","text":"<p>Info</p> <p>Changed as of 0.11.0</p> <p>From Dokku versions <code>0.5.0</code> until <code>0.11.0</code>, enabling or disabling an application's proxy would also control whether or not the application was bound to all interfaces - e.g. <code>0.0.0.0</code>. As of <code>0.11.0</code>, this is now controlled by the network plugin. Please see the network documentation for more information.</p>"},{"location":"networking/proxy-management/#implementing-a-proxy","title":"Implementing a Proxy","text":"<p>Custom plugins names must have the suffix <code>-vhosts</code> or scheduler overriding via <code>proxy:set</code> may not function as expected.</p> <p>At this time, the following dokku commands are used to interact with a complete proxy implementation.</p> <ul> <li><code>domains:add</code>: Adds a given domain to an app.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>domains:clear</code>: Clears out an app's associated domains.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>domains:disable</code>: Disables domains for an app.<ul> <li>triggers: <code>pre-disable-vhost</code></li> </ul> </li> <li><code>domains:enable</code>: Enables domains for an app.<ul> <li>triggers: <code>pre-enable-vhost</code></li> </ul> </li> <li><code>domains:remove</code>: Removes a domain from an app.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>domains:set</code>: Sets all domains for a given app.<ul> <li>triggers: <code>post-domains-update</code></li> </ul> </li> <li><code>proxy:build-config</code>: Builds - or rebuilds - external proxy configuration.<ul> <li>triggers: <code>proxy-build-config</code></li> </ul> </li> <li><code>proxy:clear-config</code>: Clears out external proxy configuration.<ul> <li>triggers: <code>proxy-clear-config</code></li> </ul> </li> <li><code>proxy:disable</code>: Disables the proxy configuration for an app.<ul> <li>triggers: <code>proxy-disable</code></li> </ul> </li> <li><code>proxy:enable</code>: Enables the proxy configuration for an app.<ul> <li>triggers: <code>proxy-enable</code></li> </ul> </li> <li><code>ports:add</code>: Adds one or more port mappings to an app<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> <li><code>ports:clear</code>: Clears out all port mappings for an app.<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> <li><code>ports:remove</code>: Removes one or more port mappings from an app.<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> <li><code>ports:set</code>: Sets all port mappings for an app.<ul> <li>triggers: <code>post-proxy-ports-update</code></li> </ul> </li> </ul> <p>Proxy implementations may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins.</p> <p>Individual proxy implementations may trigger app rebuilds, depending on how proxy metadata is exposed for the proxy implementation.</p> <p>Finally, proxy implementations may install extra software needed for the proxy itself in whatever manner deemed fit. Proxy software can run on the host itself or within a running Docker container with either exposed ports or host networking.</p>"},{"location":"networking/proxies/caddy/","title":"Caddy Proxy","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>Dokku provides integration with the Caddy proxy service by utilizing the Docker label-based integration implemented by Caddy.</p> <pre><code>caddy:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a caddy report for one or more apps\ncaddy:logs [--num num] [--tail]          # Display caddy log output\ncaddy:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an caddy property for an app\ncaddy:show-config &lt;app&gt;                  # Display caddy compose config\ncaddy:start                              # Starts the caddy server\ncaddy:stop                               # Stops the caddy server\n</code></pre>"},{"location":"networking/proxies/caddy/#requirements","title":"Requirements","text":"<p>Using the <code>caddy</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/caddy/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy.</p> <p>The Caddy plugin has specific rules for routing requests:</p> <ul> <li>Caddy integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While Caddy will respect labels associated with other containers, only <code>web</code> containers have Caddy labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported.</li> <li>Caddy will automatically enable SSL if the letsencrypt email property is set. SSL will be disabled otherwise.</li> <li>If no <code>http:80</code> mapping is found, the first <code>http</code> port mapping is used for http requests.</li> <li>If no <code>https:443</code> mapping is found, the first <code>https</code> port mapping is used for https requests.</li> <li>If no <code>https</code> mapping is found, the container port from <code>http:80</code> will be used for https requests.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/caddy/#switching-to-caddy","title":"Switching to Caddy","text":"<p>To use the Caddy plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app caddy\n</code></pre> <p>This will enable the docker label-based Caddy integration. All future deploys will inject the correct labels for Caddy to read and route requests to containers. Due to the docker label-based integration used by Caddy, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/caddy/#starting-caddy-container","title":"Starting Caddy container","text":"<p>Caddy can be started via the <code>caddy:start</code> command. This will start a Caddy container via the <code>docker compose up</code> command.</p> <pre><code>dokku caddy:start\n</code></pre>"},{"location":"networking/proxies/caddy/#stopping-the-caddy-container","title":"Stopping the Caddy container","text":"<p>Caddy may be stopped via the <code>caddy:stop</code> command.</p> <pre><code>dokku caddy:stop\n</code></pre> <p>The Caddy container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/caddy/#showing-the-caddy-compose-config","title":"Showing the Caddy compose config","text":"<p>For debugging purposes, it may be useful to show the Caddy compose config. This can be achieved via the <code>caddy:show-config</code> command.</p> <pre><code>dokku caddy:show-config\n</code></pre>"},{"location":"networking/proxies/caddy/#customizing-the-caddy-container-image","title":"Customizing the Caddy container image","text":"<p>While the default Caddy image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global image lucaslorentz/caddy-docker-proxy:2.7\n</code></pre>"},{"location":"networking/proxies/caddy/#checking-the-caddy-containers-logs","title":"Checking the Caddy container's logs","text":"<p>It may be necessary to check the Caddy container's logs to ensure that Caddy is operating as expected. This can be performed with the <code>caddy:logs</code> command.</p> <pre><code>dokku caddy:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku caddy:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the caddy container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/caddy/#changing-the-caddy-log-level","title":"Changing the Caddy log level","text":"<p>Caddy log output is set to <code>ERROR</code> by default. It may be changed by setting the <code>log-level</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global log-level DEBUG\n</code></pre> <p>After modifying,  the Caddy container will need to be restarted.</p>"},{"location":"networking/proxies/caddy/#ssl-configuration","title":"SSL Configuration","text":"<p>The caddy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/caddy/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, the Caddy container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/caddy/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku caddy:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the Caddy container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/caddy/#using-caddys-internal-tls-server","title":"Using Caddy's Internal TLS server","text":"<p>To switch to Caddy's internal TLS server for certificate provisioning, set the <code>tls-internal</code> property. This can only be set on a per-app basis.</p> <pre><code>dokku caddy:set node-js-app tls-internal true\n</code></pre>"},{"location":"networking/proxies/caddy/#displaying-caddy-reports-for-an-app","title":"Displaying Caddy reports for an app","text":"<p>You can get a report about the app's Caddy config using the <code>caddy:report</code> command:</p> ShellOutput <pre><code>dokku caddy:report\n</code></pre> <pre><code>=====&gt; node-js-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n=====&gt; python-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n=====&gt; ruby-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku caddy:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app caddy information\n       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7\n       Caddy letsencrypt email:\n       Caddy letsencrypt server:\n       Caddy log level:               ERROR\n       Caddy polling interval:        5s\n       Caddy tls internal:            false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku caddy:report node-js-app --caddy-image\n</code></pre>"},{"location":"networking/proxies/haproxy/","title":"Haproxy Proxy","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>Dokku provides integration with the Haproxy proxy service by utilizing the Docker label-based integration implemented by EasyHaproxy.</p> <pre><code>haproxy:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a haproxy report for one or more apps\nhaproxy:logs [--num num] [--tail]          # Display haproxy log output\nhaproxy:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an haproxy property for an app\nhaproxy:show-config &lt;app&gt;                  # Display haproxy compose config\nhaproxy:start                              # Starts the haproxy server\nhaproxy:stop                               # Stops the haproxy server\n</code></pre>"},{"location":"networking/proxies/haproxy/#requirements","title":"Requirements","text":"<p>Using the <code>haproxy</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/haproxy/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy.</p> <p>The Haproxy plugin has specific rules for routing requests:</p> <ul> <li>Haproxy integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While Haproxy will respect labels associated with other containers, only <code>web</code> containers have Haproxy labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported at this time.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/haproxy/#switching-to-haproxy","title":"Switching to Haproxy","text":"<p>To use the Haproxy plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app haproxy\n</code></pre> <p>This will enable the docker label-based Haproxy integration. All future deploys will inject the correct labels for Haproxy to read and route requests to containers. Due to the docker label-based integration used by Haproxy, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/haproxy/#starting-haproxy-container","title":"Starting Haproxy container","text":"<p>Haproxy can be started via the <code>haproxy:start</code> command. This will start a Haproxy container via the <code>docker compose up</code> command.</p> <pre><code>dokku haproxy:start\n</code></pre>"},{"location":"networking/proxies/haproxy/#stopping-the-haproxy-container","title":"Stopping the Haproxy container","text":"<p>Haproxy may be stopped via the <code>haproxy:stop</code> command.</p> <pre><code>dokku haproxy:stop\n</code></pre> <p>The Haproxy container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/haproxy/#showing-the-haproxy-compose-config","title":"Showing the Haproxy compose config","text":"<p>For debugging purposes, it may be useful to show the Haproxy compose config. This can be achieved via the <code>haproxy:show-config</code> command.</p> <pre><code>dokku haproxy:show-config\n</code></pre>"},{"location":"networking/proxies/haproxy/#customizing-the-haproxy-container-image","title":"Customizing the Haproxy container image","text":"<p>While the default Haproxy image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global image byjg/easy-haproxy:4.0.0\n</code></pre>"},{"location":"networking/proxies/haproxy/#checking-the-haproxy-containers-logs","title":"Checking the Haproxy container's logs","text":"<p>It may be necessary to check the Haproxy container's logs to ensure that Haproxy is operating as expected. This can be performed with the <code>haproxy:logs</code> command.</p> <pre><code>dokku haproxy:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku haproxy:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the vector container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/haproxy/#changing-the-haproxy-log-level","title":"Changing the Haproxy log level","text":"<p>Haproxy log output is set to <code>ERROR</code> by default. It may be changed by setting the <code>log-level</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global log-level DEBUG\n</code></pre> <p>After modifying,  the Haproxy container will need to be restarted.</p>"},{"location":"networking/proxies/haproxy/#ssl-configuration","title":"SSL Configuration","text":"<p>The haproxy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/haproxy/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, the Haproxy container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/haproxy/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku haproxy:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the Haproxy container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/haproxy/#displaying-haproxy-reports-for-an-app","title":"Displaying Haproxy reports for an app","text":"<p>You can get a report about the app's Haproxy config using the <code>haproxy:report</code> command:</p> ShellOutput <pre><code>dokku haproxy:report\n</code></pre> <pre><code>=====&gt; node-js-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n=====&gt; python-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n=====&gt; ruby-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku haproxy:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app haproxy information\n       Haproxy image:                   byjg/easy-haproxy:4.0.0\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku haproxy:report node-js-app --haproxy-image\n</code></pre>"},{"location":"networking/proxies/nginx/","title":"Nginx Proxy","text":"<p>Dokku uses nginx as its server for routing requests to specific applications. By default, access and error logs are written for each app to <code>/var/log/nginx/${APP}-access.log</code> and <code>/var/log/nginx/${APP}-error.log</code> respectively</p> <pre><code>nginx:access-logs &lt;app&gt; [-t]             # Show the nginx access logs for an application (-t follows)\nnginx:error-logs &lt;app&gt; [-t]              # Show the nginx error logs for an application (-t follows)\nnginx:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a nginx report for one or more apps\nnginx:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an nginx property for an app\nnginx:show-config &lt;app&gt;                  # Display app nginx config\nnginx:start                              # Starts the nginx server\nnginx:stop                               # Stops the nginx server\nnginx:validate-config [&lt;app&gt;] [--clean]  # Validates and optionally cleans up invalid nginx configurations\n</code></pre>"},{"location":"networking/proxies/nginx/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided.</p>"},{"location":"networking/proxies/nginx/#request-proxying","title":"Request Proxying","text":"<p>By default, the <code>web</code> process is the only process proxied by the nginx proxy implementation. Proxying to other process types may be handled by a custom <code>nginx.conf.sigil</code> file, as generally described below</p> <p>Nginx will proxy the requests in a round-robin balancing fashion to the different deployed (scaled) containers running the <code>web</code> proctype. This way, the host's resources can be fully leveraged for single-threaded applications (e.g. <code>dokku ps:scale node-js-app web=4</code> on a 4-core machine).</p> <p>Note</p> <p>Due to how the plugin is implemented, if an app successfully starts up <code>web</code> containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger <code>dokku proxy:build-config $APP</code> in order to ensure requests route to the new web containers.</p>"},{"location":"networking/proxies/nginx/#starting-nginx","title":"Starting nginx","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>The nginx server can be started via <code>nginx:start</code>.</p> <pre><code>dokku nginx:start\n</code></pre>"},{"location":"networking/proxies/nginx/#stopping-nginx","title":"Stopping nginx","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>The nginx server can be stopped via <code>nginx:stop</code>.</p> <pre><code>dokku nginx:stop\n</code></pre>"},{"location":"networking/proxies/nginx/#binding-to-specific-addresses","title":"Binding to specific addresses","text":"<p>New</p> <p>Introduced in 0.19.2</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>By default, nginx will listen to all interfaces (<code>[::]</code> for IPv6, <code>0.0.0.0</code> for IPv4) when proxying requests to applications. This may be changed using the <code>bind-address-ipv4</code> and <code>bind-address-ipv6</code> properties. This is useful in cases where the proxying should be internal to a network or if there are multiple network interfaces that should respond with different content.</p> <pre><code>dokku nginx:set node-js-app bind-address-ipv4 127.0.0.1\ndokku nginx:set node-js-app bind-address-ipv6 ::1\n</code></pre> <p>This may be reverted by setting an empty bind address.</p> <pre><code>dokku nginx:set node-js-app bind-address-ipv4\ndokku nginx:set node-js-app bind-address-ipv6\n</code></pre> <p>Warning</p> <p>Validation is not performed on either value.</p> <p>Users with apps that contain a custom <code>nginx.conf.sigil</code> file will need to modify the files to respect the new <code>NGINX_BIND_ADDRESS_IPV4</code> and <code>NGINX_BIND_ADDRESS_IPV6</code> variables.</p>"},{"location":"networking/proxies/nginx/#hsts-header","title":"HSTS Header","text":"<p>New</p> <p>Introduced in 0.20.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via <code>nginx:set</code>:</p> <pre><code>dokku nginx:set node-js-app hsts true\ndokku nginx:set node-js-app hsts false\n</code></pre> <p>The following options are also available via the <code>nginx:set</code> command:</p> <ul> <li><code>hsts</code> (type: boolean, default: <code>true</code>): Enables or disables HSTS for your application.</li> <li><code>hsts-include-subdomains</code> (type: boolean, default: <code>true</code>): Tells the browser that the HSTS policy also applies to all subdomains of the current domain.</li> <li><code>hsts-max-age</code> (type: integer, default: <code>15724800</code>): Time in seconds to cache HSTS configuration.</li> <li><code>hsts-preload</code> (type: boolean, default: <code>false</code>): Tells most major web browsers to include the domain in their HSTS preload lists.</li> </ul> <p>Beware that if you enable the header and a subsequent deploy of your application results in an HTTP deploy (for whatever reason), the way the header works means that a browser will not attempt to request the HTTP version of your site if the HTTPS version fails until the max-age is reached.</p>"},{"location":"networking/proxies/nginx/#globally-disabling-the-hsts-header","title":"Globally disabling the HSTS Header","text":"<p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>HSTS Header can be disabled for all apps by setting the <code>hsts</code> property to false after passing the <code>--global</code> flag to <code>nginx:set</code>.</p> <pre><code>dokku nginx:set --global hsts false\n</code></pre> <p>Once the HSTS setting is disabled globally, it can be re-enabled on a per-app basis by setting the <code>hsts</code> property as normal.</p> <pre><code>dokku nginx:set node-js-app hsts true\n</code></pre>"},{"location":"networking/proxies/nginx/#running-behind-another-proxy-configuring-x-forwarded-headers","title":"Running behind another proxy \u2014 configuring <code>X-Forwarded-*</code> headers","text":"<p>Dokku's default Nginx configuration passes the de-facto standard HTTP headers <code>X-Forwarded-For</code>, <code>X-Forwarded-Proto</code>, and <code>X-Forwarded-Port</code> to your application. These headers indicate the IP address of the original client making the request, the protocol of the original request (HTTP or HTTPS), and the port number of the original request, respectively.</p> <p>If you have another HTTP proxy sitting in between the end user and your server (for example, a load balancer, or a CDN), then the values of these headers will contain information about (e.g. the IP address of) the the closest proxy, and not the end user.</p> <p>To fix this, assuming that the other proxy also passes <code>X-Forwarded-*</code> headers, which in turn contain information about the end user, you can tell Nginx include those values in the <code>X-Forwarded-*</code> headers that it sends to your application. You can do this via <code>nginx:set</code>, like so:</p> <pre><code>dokku nginx:set node-js-app x-forwarded-for-value '$http_x_forwarded_for'\ndokku nginx:set node-js-app x-forwarded-port-value '$http_x_forwarded_port'\ndokku nginx:set node-js-app x-forwarded-proto-value '$http_x_forwarded_proto'\n</code></pre> <p>However, note that you should only do this if:</p> <ol> <li>Requests to your website always go through a trusted proxy.</li> <li>That proxy is configured to send the aforementioned <code>X-Forwarded-*</code> headers.</li> </ol> <p>Otherwise, if it's possible for clients to make HTTP requests directly against your server, bypassing the other proxy, or if the other proxy is not configured to set these headers, then a client can basically pass any arbitrary values for these headers (which your app then presumably reads) and thereby fake an IP address, for example.</p> <p>There's also the <code>X-Forwarded-Ssl</code> header which a less common alternative to <code>X-Forwarded-Proto</code> \u2014 and because of that, isn't included in Dokku's default Nginx configuration. But you can tell Nginx to send this header as well, if necessary.</p> <pre><code># force-setting value to `on`\ndokku nginx:set node-js-app x-forwarded-ssl on\n\n# force-setting value to `off`\ndokku nginx:set node-js-app x-forwarded-ssl off\n\n# removing the value from nginx.conf (default)\ndokku nginx:set node-js-app x-forwarded-ssl\n</code></pre>"},{"location":"networking/proxies/nginx/#checking-access-logs","title":"Checking access logs","text":"<p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>You may check nginx access logs via the <code>nginx:access-logs</code> command. This assumes that app access logs are being stored in <code>/var/log/nginx/$APP-access.log</code>, as is the default in the generated <code>nginx.conf</code>.</p> <pre><code>dokku nginx:access-logs node-js-app\n</code></pre> <p>You may also follow the logs by specifying the <code>-t</code> flag.</p> <pre><code>dokku nginx:access-logs node-js-app -t\n</code></pre>"},{"location":"networking/proxies/nginx/#checking-error-logs","title":"Checking error logs","text":"<p>You may check nginx error logs via the <code>nginx:error-logs</code> command. This assumes that app error logs are being stored in <code>/var/log/nginx/$APP-error.log</code>, as is the default in the generated <code>nginx.conf</code>.</p> <pre><code>dokku nginx:error-logs node-js-app\n</code></pre> <p>You may also follow the logs by specifying the <code>-t</code> flag.</p> <pre><code>dokku nginx:error-logs node-js-app -t\n</code></pre>"},{"location":"networking/proxies/nginx/#changing-log-path","title":"Changing log path","text":"<p>New</p> <p>Introduced in 0.20.1</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>The path to where log files are stored can be changed by calling the <code>nginx:set</code> command with the following options:</p> <ul> <li><code>access-log-path</code> (type: string, default: <code>${NGINX_LOG_ROOT}/${APP}-access.log</code>): Log path for nginx access logs</li> <li><code>error-log-path</code> (type: string, default: <code>${NGINX_LOG_ROOT}/${APP}-error.log</code>): Log path for nginx error logs</li> </ul> <p>The defaults should not be changed without verifying that the paths will be writeable by nginx. However, this setting is useful for enabling or disabling logging by setting the values to <code>off</code>.</p> <pre><code>dokku nginx:set node-js-app access-log-path off\ndokku nginx:set node-js-app error-log-path off\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku nginx:set node-js-app access-log-path\ndokku nginx:set node-js-app error-log-path\n</code></pre> <p>In all cases, the nginx config must be regenerated after setting the above values.</p>"},{"location":"networking/proxies/nginx/#changing-log-format","title":"Changing log format","text":"<p>New</p> <p>Introduced in 0.22.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>The format of the access log can be changed by calling the <code>nginx:set</code> command as follows:</p> <pre><code>dokku nginx:set node-js-app access-log-format custom-format\n</code></pre> <p>Prior to changing the log-format, log formats should be specified at a file such as <code>/etc/nginx/conf.d/00-log-formats.conf</code>. This will ensure they are available within your app's nginx context. For instance, the following may be added to the above file. It only needs to be specified once to be used for all apps.</p> <pre><code># /etc/nginx/conf.d/00-log-formats.conf\n# escape=json was added in nginx 1.11.8\nlog_format json_combined escape=json\n  '{'\n    '\"time_local\":\"$time_local\",'\n    '\"remote_addr\":\"$remote_addr\",'\n    '\"remote_user\":\"$remote_user\",'\n    '\"request\":\"$request\",'\n    '\"status\":\"$status\",'\n    '\"body_bytes_sent\":\"$body_bytes_sent\",'\n    '\"request_time\":\"$request_time\",'\n    '\"http_referrer\":\"$http_referer\",'\n    '\"http_user_agent\":\"$http_user_agent\"'\n  '}';\n</code></pre> <p>Next, the format should be set for the given app.</p> <pre><code>dokku nginx:set node-js-app access-log-format json_combined\n</code></pre> <p>Finally, a proxy rebuild will change the format as desired.</p> <pre><code>dokku proxy:build-config node-js-app\n</code></pre>"},{"location":"networking/proxies/nginx/#specifying-a-read-timeout","title":"Specifying a read timeout","text":"<p>New</p> <p>Introduced in 0.21.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>When proxying requests to your applications, it may be useful to specify a proxy read timeout. This can be done via the <code>nginx:set</code> command as follows:</p> <pre><code>dokku nginx:set node-js-app proxy-read-timeout 120s\n</code></pre> <p>The default value is <code>60s</code>, and all numeric values must have a trailing time value specified (<code>s</code> for seconds, <code>m</code> for minutes).</p> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku nginx:set node-js-app proxy-read-timeout\n</code></pre> <p>In all cases, the nginx config must be regenerated after setting the above value.</p>"},{"location":"networking/proxies/nginx/#specifying-a-custom-client_max_body_size","title":"Specifying a custom client_max_body_size","text":"<p>New</p> <p>Introduced in 0.23.0</p> <p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>Users can override the default <code>client_max_body_size</code> value - which limits file uploads - via <code>nginx:set</code>. Changing this value will only apply to every <code>server</code> stanza of the default <code>nginx.conf.sigil</code>; users of custom <code>nginx.conf.sigil</code> files must update their templates to support the new value.</p> <pre><code>dokku nginx:set node-js-app client-max-body-size 50m\n</code></pre> <p>The default value is empty string, which will result in nginx falling back to any configured, higher-level defaults (or <code>1m</code> if unconfigued; all numerical values must have a size unit specified (<code>k</code> for kilobytes, <code>m</code> for megabytes).</p> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku nginx:set node-js-app client-max-body-size\n</code></pre> <p>In all cases, the nginx config must be regenerated after setting the above value.</p> <p>Changing this value when using the PHP buildpack (or any other buildpack that uses an intermediary server) will require changing the value in the server config shipped with that buildpack. Consult your buildpack documentation for further details.</p>"},{"location":"networking/proxies/nginx/#showing-the-nginx-config","title":"Showing the nginx config","text":"<p>For debugging purposes, it may be useful to show the nginx config. This can be achieved via the <code>nginx:show-config</code> command.</p> <pre><code>dokku nginx:show-config node-js-app\n</code></pre>"},{"location":"networking/proxies/nginx/#validating-nginx-configs","title":"Validating nginx configs","text":"<p>It may be desired to validate an nginx config outside of the deployment process. To do so, run the <code>nginx:validate-config</code> command. With no arguments, this will validate all app nginx configs, one at a time. A minimal wrapper nginx config is generated for each app's nginx config, upon which <code>nginx -t</code> will be run.</p> <pre><code>dokku nginx:validate-config\n</code></pre> <p>As app nginx configs are actually executed within a shared context, it is possible for an individual config to be invalid when being validated standalone but also be valid within the global server context. As such, the exit code for the <code>nginx:validate-config</code> command is the exit code of <code>nginx -t</code> against the server's real nginx config.</p> <p>The <code>nginx:validate-config</code> command also takes an optional <code>--clean</code> flag. If specified, invalid nginx configs will be removed.</p> <p>Warning</p> <p>Invalid app nginx config's will be removed even if the config is valid in the global server context.</p> <pre><code>dokku nginx:validate-config --clean\n</code></pre> <p>The <code>--clean</code> flag may also be specified for a given app:</p> <pre><code>dokku nginx:validate-config node-js-app --clean\n</code></pre>"},{"location":"networking/proxies/nginx/#customizing-the-nginx-configuration","title":"Customizing the nginx configuration","text":"<p>New</p> <p>Introduced in 0.5.0</p> <p>Dokku uses a templating library by the name of sigil to generate nginx configuration for each app. This may be overriden by committing the default configuration template to a file named <code>nginx.conf.sigil</code> in the root of the app repository.</p> <p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>nginx.conf.sigil</code> file to use for a given app. This can be done via the <code>nginx:set</code> command. If a value is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no <code>nginx.conf.sigil</code>.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>nginx.conf.sigil</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>nginx.conf.sigil</code> extracted directly from the source code. Both cases will respect the configured <code>nginx-conf-sigil-path</code> property value.</p> <pre><code>dokku nginx:set node-js-app nginx-conf-sigil-path .dokku/nginx.conf.sigil\n</code></pre> <p>This property can also be changed globally, which will take into effect if there is no value at the app level.</p> <pre><code>dokku nginx:set --global nginx-conf-sigil-path .dokku/nginx.conf.sigil\n</code></pre> <p>In either case, the value can be reset by specifying an empty value.</p> <pre><code>dokku nginx:set node-js-app nginx-conf-sigil-path\ndokku nginx:set --global nginx-conf-sigil-path\n</code></pre> <p>Info</p> <p>The default template may change with new releases of Dokku. Please refer to the appropriate template file version for your Dokku version, and make sure to look out for changes when you upgrade.</p>"},{"location":"networking/proxies/nginx/#disabling-custom-nginx-config","title":"Disabling custom nginx config","text":"<p>Note</p> <p>Changing this value globally or on a per-app basis will require rebuilding the nginx config via the <code>proxy:build-config</code> command.</p> <p>While enabled by default, using a custom nginx config can be disabled via <code>nginx:set</code>. This may be useful in cases where you do not want to allow users to override any higher-level customization of app nginx config.</p> <pre><code># enable fetching custom config (default)\ndokku nginx:set node-js-app disable-custom-config false\n\n# disable fetching custom config\ndokku nginx:set node-js-app disable-custom-config true\n</code></pre> <p>Unsetting this value is the same as enabling custom nginx config usage.</p>"},{"location":"networking/proxies/nginx/#available-template-variables","title":"Available template variables","text":"<pre><code>{{ .APP }}                          Application name\n{{ .APP_SSL_PATH }}                 Path to SSL certificate and key\n{{ .DOKKU_ROOT }}                   Global Dokku root directory (ex: app dir would be `{{ .DOKKU_ROOT }}/{{ .APP }}`)\n{{ .PROXY_PORT }}                   Non-SSL nginx listener port (same as `DOKKU_PROXY_PORT` config var)\n{{ .PROXY_SSL_PORT }}               SSL nginx listener port (same as `DOKKU_PROXY_SSL_PORT` config var)\n{{ .NOSSL_SERVER_NAME }}            List of non-SSL VHOSTS\n{{ .PROXY_PORT_MAP }}               List of port mappings (same as the `map` ports property)\n{{ .PROXY_UPSTREAM_PORTS }}         List of configured upstream ports (derived from the `map` ports property)\n{{ .SSL_INUSE }}                    Boolean set when an app is SSL-enabled\n{{ .SSL_SERVER_NAME }}              List of SSL VHOSTS\n</code></pre> <p>Finally, each process type has it's network listeners - a list of IP:PORT pairs for the respective app containers - exposed via an <code>.DOKKU_APP_${PROCESS_TYPE}_LISTENERS</code> variable - the <code>PROCESS_TYPE</code> will be upper-cased with hyphens transformed into underscores. Users can use the new variables to expose non-web processes via the nginx proxy.</p> <p>Note</p> <p>Application environment variables are available for use in custom templates. To do so, use the form of <code>{{ var \"FOO\" }}</code> to access a variable named <code>FOO</code>.</p>"},{"location":"networking/proxies/nginx/#customizing-via-configuration-files-included-by-the-default-templates","title":"Customizing via configuration files included by the default templates","text":"<p>The default nginx.conf template will include everything from your apps <code>nginx.conf.d/</code> subdirectory in the main <code>server {}</code> block (see above):</p> <pre><code>include {{ .DOKKU_ROOT }}/{{ .APP }}/nginx.conf.d/*.conf;\n</code></pre> <p>That means you can put additional configuration in separate files. To increase the client request header timeout, the following can be performed:</p> <pre><code>mkdir /home/dokku/node-js-app/nginx.conf.d/\necho 'client_header_timeout 50s;' &gt; /home/dokku/node-js-app/nginx.conf.d/timeout.conf\nchown dokku:dokku /home/dokku/node-js-app/nginx.conf.d/upload.conf\nservice nginx reload\n</code></pre> <p>The example above uses additional configuration files directly on the Dokku host. Unlike the <code>nginx.conf.sigil</code> file, these additional files will not be copied over from your application repo, and thus need to be placed in the <code>/home/dokku/node-js-app/nginx.conf.d/</code> directory manually.</p> <p>For PHP Buildpack users, you will also need to provide a <code>Procfile</code> and an accompanying <code>nginx.conf</code> file to customize the nginx config within the container. The following are example contents for your <code>Procfile</code></p> <pre><code>web: vendor/bin/heroku-php-nginx -C nginx.conf -i php.ini php/\n</code></pre> <p>Your <code>nginx.conf</code> file - not to be confused with Dokku's <code>nginx.conf.sigil</code> - would also need to be configured as shown in this example:</p> <pre><code>client_header_timeout 50s;\nlocation / {\n    index index.php;\n    try_files $uri $uri/ /index.php$is_args$args;\n}\n</code></pre> <p>Please adjust the <code>Procfile</code> and <code>nginx.conf</code> file as appropriate.</p>"},{"location":"networking/proxies/nginx/#custom-error-pages","title":"Custom Error Pages","text":"<p>By default, Dokku provides custom error pages for the following three categories of errors:</p> <ul> <li>4xx: For all non-404 errors with a 4xx response code.</li> <li>404: For \"404 Not Found\" errors.</li> <li>5xx: For all 5xx error responses</li> </ul> <p>These are provided as an alternative to the generic Nginx error page, are shared for all applications, and their contents are located on disk at <code>/var/lib/dokku/data/nginx-vhosts/dokku-errors</code>. To customize them for a specific app, create a custom <code>nginx.conf.sigil</code> as described above and change the paths to point elsewhere.</p>"},{"location":"networking/proxies/nginx/#default-site","title":"Default site","text":"<p>By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website.</p> <p>Warning</p> <p>some versions of Nginx may create a default site when installed. This site is simply a static page which says \"Welcome to Nginx\", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:</p> <pre><code>rm /etc/nginx/sites-enabled/default\ndokku nginx:stop\ndokku nginx:start\n</code></pre> <p>If services should only be accessed via their domain name, you may want to disable the default site by adding the following configuration to the global nginx configuration.</p> <p>Create the file at <code>/etc/nginx/conf.d/00-default-vhost.conf</code>:</p> <pre><code>server {\n    listen 80 default_server;\n    listen [::]:80 default_server;\n\n    # If services hosted by dokku are available via HTTPS, it is recommended\n    # to also uncomment the following section.\n    #\n    # Please note that in order to let this work, you need an SSL certificate. However\n    # it does not need to be valid. Users of Debian-based distributions can install the\n    # `ssl-cert` package with `sudo apt install ssl-cert` to automatically generate\n    # a self-signed certificate that is stored at `/etc/ssl/certs/ssl-cert-snakeoil.pem`.\n    #\n    #listen 443 ssl;\n    #listen [::]:443 ssl;\n    #ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;\n    #ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;\n\n    server_name _;\n    access_log off;\n    return 444;\n}\n</code></pre> <p>Make sure to reload nginx after creating this file by running <code>systemctl reload nginx.service</code>.</p> <p>This will catch all unknown HOST header values and close the connection without responding. You can replace the <code>return 444;</code> with <code>return 410;</code> which will cause nginx to respond with an error page.</p> <p>The configuration file must be loaded before <code>/etc/nginx/conf.d/dokku.conf</code>, so it can not be arranged as a vhost in <code>/etc/nginx/sites-enabled</code> that is only processed afterwards.</p> <p>Alternatively, you may push an app to your Dokku host with a name like \"00-default\". As long as it lists first in <code>ls /home/dokku/*/nginx.conf | head</code>, it will be used as the default nginx vhost.</p>"},{"location":"networking/proxies/nginx/#other","title":"Other","text":""},{"location":"networking/proxies/nginx/#domains-plugin","title":"Domains plugin","text":"<p>See the domain configuration documentation for more information on how to configure domains for your app.</p>"},{"location":"networking/proxies/nginx/#customizing-hostnames","title":"Customizing hostnames","text":"<p>See the customizing hostnames documentation for more information on how to configure domains for your app.</p>"},{"location":"networking/proxies/nginx/#disabling-vhosts","title":"Disabling VHOSTS","text":"<p>See the disabling vhosts documentation for more information on how to disable domain usage for your app.</p>"},{"location":"networking/proxies/nginx/#ssl-configuration","title":"SSL Configuration","text":"<p>See the ssl documentation for more information on how to configure SSL certificates for your application.</p>"},{"location":"networking/proxies/nginx/#disabling-nginx","title":"Disabling Nginx","text":"<p>See the proxy documentation for more information on how to disable nginx as the proxy implementation for your app.</p>"},{"location":"networking/proxies/nginx/#managing-proxy-port-mappings","title":"Managing Proxy Port mappings","text":"<p>See the ports documentation for more information on how to manage ports proxied for your app.</p>"},{"location":"networking/proxies/nginx/#regenerating-nginx-config","title":"Regenerating nginx config","text":"<p>See the proxy documentation for more information on how to rebuild the nginx proxy configuration for your app.</p>"},{"location":"networking/proxies/openresty/","title":"OpenResty Proxy","text":"<p>New</p> <p>Introduced in 0.31.0</p> <p>Dokku can provide integration with the OpenResty proxy service by utilizing the Docker label-based integration implemented by openresty-docker-proxy.</p> <pre><code>openresty:report [&lt;app&gt;] [&lt;flag&gt;]            # Displays a openresty report for one or more apps\nopenresty:logs [--num num] [--tail]          # Display openresty log output\nopenresty:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)     # Set or clear an openresty property for an app\nopenresty:show-config &lt;app&gt;                  # Display openresty compose config\nopenresty:start                              # Starts the openresty server\nopenresty:stop                               # Stops the openresty server\n</code></pre>"},{"location":"networking/proxies/openresty/#requirements","title":"Requirements","text":"<p>Using the <code>openresty</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/openresty/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty.</p> <p>The OpenResty plugin has specific rules for routing requests:</p> <ul> <li>OpenResty integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While OpenResty will respect labels associated with other containers, only <code>web</code> containers have OpenResty labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported at this time.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/openresty/#switching-to-openresty","title":"Switching to OpenResty","text":"<p>To use the OpenResty plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app openresty\n</code></pre> <p>This will enable the docker label-based OpenResty integration. All future deploys will inject the correct labels for OpenResty to read and route requests to containers. Due to the docker label-based integration used by OpenResty, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/openresty/#starting-openresty-container","title":"Starting OpenResty container","text":"<p>OpenResty can be started via the <code>openresty:start</code> command. This will start a OpenResty container via the <code>docker compose up</code> command.</p> <pre><code>dokku openresty:start\n</code></pre>"},{"location":"networking/proxies/openresty/#stopping-the-openresty-container","title":"Stopping the OpenResty container","text":"<p>OpenResty may be stopped via the <code>openresty:stop</code> command.</p> <pre><code>dokku openresty:stop\n</code></pre> <p>The OpenResty container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/openresty/#showing-the-openresty-compose-config","title":"Showing the OpenResty compose config","text":"<p>For debugging purposes, it may be useful to show the OpenResty compose config. This can be achieved via the <code>openresty:show-config</code> command.</p> <pre><code>dokku openresty:show-config\n</code></pre>"},{"location":"networking/proxies/openresty/#customizing-the-openresty-container-image","title":"Customizing the OpenResty container image","text":"<p>While the default OpenResty image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku openresty:set --global image dokku/openresty-docker-proxy:0.5.6\n</code></pre>"},{"location":"networking/proxies/openresty/#checking-the-openresty-containers-logs","title":"Checking the OpenResty container's logs","text":"<p>It may be necessary to check the OpenResty container's logs to ensure that OpenResty is operating as expected. This can be performed with the <code>openresty:logs</code> command.</p> <pre><code>dokku openresty:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku openresty:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the openresty container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/openresty/#customizing-openresty-settings-for-an-app","title":"Customizing Openresty Settings for an app","text":""},{"location":"networking/proxies/openresty/#openresty-properties","title":"OpenResty Properties","text":"<p>The OpenResty plugin supports all properties supported by the <code>nginx:set</code> command via <code>openresty:set</code>. At this time, please consult the nginx documentation for more information on what properties are available.</p> <p>Please note that the oldest running container will be used for OpenResty configuration, and thus newer config may not apply until older app containers are retired during/after a deploy, depending on your zero-downtime settings.</p>"},{"location":"networking/proxies/openresty/#custom-openresty-templates","title":"Custom OpenResty Templates","text":"<p>At this time, the OpenResty plugin does not allow complete customization of the template used to manage an app's vhost. Apps will use a template provided by the OpenResty container to proxy requests. See the next section for documentation on how to configure portions of the template.</p>"},{"location":"networking/proxies/openresty/#injecting-custom-snippets-into-the-openresty-config","title":"Injecting custom snippets into the OpenResty config","text":"<p>The OpenResty plugin allows users to specify templates in their repository for auto-injection into the OpenResty config. Please note that this configuration should be validated prior to deployment or may cause outages in your OpenResty proxy layer.</p> <p>The following folders within an app repository may have <code>*.conf</code> files that will be automatically injected into the OpenResty config.</p> <ul> <li><code>openresty/http-includes/</code>: Injected in the <code>server</code> block serving http(s) requests for the app.</li> <li><code>openresty/http-location-includes/</code>: Injected in the <code>location</code> block that proxies to the app in the app's respective <code>server</code> block.</li> </ul>"},{"location":"networking/proxies/openresty/#ssl-configuration","title":"SSL Configuration","text":"<p>The OpenResty plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/openresty/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku openresty:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/openresty/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku openresty:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/openresty/#displaying-openresty-reports-for-an-app","title":"Displaying OpenResty reports for an app","text":"<p>You can get a report about the app's OpenResty config using the <code>openresty:report</code> command:</p> ShellOutput <pre><code>dokku openresty:report\n</code></pre> <pre><code>=====&gt; node-js-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n=====&gt; python-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n=====&gt; ruby-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku openresty:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app openresty information\n       Openresty image:                   dokku/openresty-docker-proxy:0.5.6\n       Openresty letsencrypt email:       automated@dokku.sh\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku openresty:report node-js-app --openresty-letsencrypt-email\n</code></pre>"},{"location":"networking/proxies/traefik/","title":"Traefik Proxy","text":"<p>New</p> <p>Introduced in 0.28.0</p> <p>Dokku provides integration with the Traefik proxy service by utilizing the Docker label-based integration implemented by Traefik.</p> <pre><code>traefik:report [&lt;app&gt;] [&lt;flag&gt;]          # Displays a traefik report for one or more apps\ntraefik:logs [--num num] [--tail]        # Display traefik log output\ntraefik:set &lt;app&gt; &lt;property&gt; (&lt;value&gt;)   # Set or clear an traefik property for an app\ntraefik:show-config &lt;app&gt;                # Display traefik compose config\ntraefik:start                            # Starts the traefik server\ntraefik:stop                             # Stops the traefik server\n</code></pre>"},{"location":"networking/proxies/traefik/#requirements","title":"Requirements","text":"<p>Using the <code>traefik</code> plugin integration requires the <code>docker-compose-plugin</code> for Docker. See this document from the Docker documentation for more information on the installation process for the <code>docker-compose-plugin</code>.</p>"},{"location":"networking/proxies/traefik/#usage","title":"Usage","text":"<p>Warning</p> <p>As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik.</p> <p>The Traefik plugin has specific rules for routing requests:</p> <ul> <li>Traefik integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.</li> <li>While Traefik will respect labels associated with other containers, only <code>web</code> containers have Traefik labels injected by the plugin.</li> <li>Only <code>http:80</code> and <code>https:443</code> port mappings are supported.</li> <li>If no <code>http:80</code> mapping is found, the first <code>http</code> port mapping is used for http requests.</li> <li>If no <code>https:443</code> mapping is found, the first <code>https</code> port mapping is used for https requests.</li> <li>If no <code>https</code> mapping is found, the container port from <code>http:80</code> will be used for https requests.</li> <li>Requests are routed as soon as the container is running and passing healthchecks.</li> </ul>"},{"location":"networking/proxies/traefik/#switching-to-traefik","title":"Switching to Traefik","text":"<p>To use the Traefik plugin, use the <code>proxy:set</code> command for the app in question:</p> <pre><code>dokku proxy:set node-js-app traefik\n</code></pre> <p>This will enable the docker label-based Traefik integration. All future deploys will inject the correct labels for Traefik to read and route requests to containers. Due to the docker label-based integration used by Traefik, a single deploy or rebuild will be required before requests will route successfully.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>Any changes to domains or port mappings will also require either a deploy or rebuild.</p>"},{"location":"networking/proxies/traefik/#starting-traefik-container","title":"Starting Traefik container","text":"<p>Traefik can be started via the <code>traefik:start</code> command. This will start a Traefik container via the <code>docker compose up</code> command.</p> <pre><code>dokku traefik:start\n</code></pre>"},{"location":"networking/proxies/traefik/#stopping-the-traefik-container","title":"Stopping the Traefik container","text":"<p>Traefik may be stopped via the <code>traefik:stop</code> command.</p> <pre><code>dokku traefik:stop\n</code></pre> <p>The Traefik container will be stopped and removed from the system. If the container is not running, this command will do nothing.</p>"},{"location":"networking/proxies/traefik/#showing-the-traefik-compose-config","title":"Showing the Traefik compose config","text":"<p>For debugging purposes, it may be useful to show the Traefik compose config. This can be achieved via the <code>traefik:show-config</code> command.</p> <pre><code>dokku traefik:show-config\n</code></pre>"},{"location":"networking/proxies/traefik/#customizing-the-traefik-container-image","title":"Customizing the Traefik container image","text":"<p>While the default Traefik image is hardcoded, users may specify an alternative by setting the <code>image</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global image traefik:v2.8\n</code></pre>"},{"location":"networking/proxies/traefik/#checking-the-traefik-containers-logs","title":"Checking the Traefik container's logs","text":"<p>It may be necessary to check the Traefik container's logs to ensure that Traefik is operating as expected. This can be performed with the <code>traefik:logs</code> command.</p> <pre><code>dokku traefik:logs\n</code></pre> <p>This command also supports the following modifiers:</p> <pre><code>--num NUM        # the number of lines to display\n--tail           # continually stream logs\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku traefik:logs --tail --num 10\n</code></pre> <p>The above command will show logs continually from the traefik container, with an initial history of 10 log lines</p>"},{"location":"networking/proxies/traefik/#changing-the-traefik-log-level","title":"Changing the Traefik log level","text":"<p>Traefik log output is set to <code>ERROR</code> by default. It may be changed by setting the <code>log-level</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global log-level DEBUG\n</code></pre> <p>After modifying, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#setting-rule-priority","title":"Setting rule priority","text":"<p>By default, app deployments will result in the newer traefik rules using a higher priority in order to have any newer rules respected by Traefik. Rule priorities will always increase according to the current unix timestamp. The priority may be fixed by setting the app-level <code>priority</code> property:</p> <pre><code>dokku traefik:set node-js-app priority 12345\n</code></pre> <p>After modifying, the app container will need to be recreated via a <code>ps:rebuild</code> or an app deployment.</p>"},{"location":"networking/proxies/traefik/#ssl-configuration","title":"SSL Configuration","text":"<p>The traefik plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the <code>certs</code> plugin are ignored.</p>"},{"location":"networking/proxies/traefik/#enabling-letsencrypt-integration","title":"Enabling letsencrypt integration","text":"<p>By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the <code>letsencrypt-email</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global letsencrypt-email automated@dokku.sh\n</code></pre> <p>After enabling, apps will need to be rebuilt and the Traefik container will need to be restarted. All http requests will then be redirected to https.</p>"},{"location":"networking/proxies/traefik/#customizing-the-letsencrypt-server","title":"Customizing the letsencrypt server","text":"<p>The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the <code>letsencrypt-server</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory\n</code></pre> <p>After enabling, the Traefik container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.</p>"},{"location":"networking/proxies/traefik/#api-access","title":"API Access","text":"<p>Traefik exposes an API and Dashboard, which Dokku disables by default for security reasons. It can be exposed and customized as described below.</p>"},{"location":"networking/proxies/traefik/#enabling-the-api","title":"Enabling the api","text":"<p>Warning</p> <p>Users enabling the dashboard should also enable api basic auth.</p> <p>By default, the api is disabled. To enable, set the <code>api</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global api true\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#enabling-the-dashboard","title":"Enabling the dashboard","text":"<p>Warning</p> <p>Users enabling the dashboard should also enable api basic auth.</p> <p>By default, the dashboard is disabled. To enable, set the <code>dashboard</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global dashboard true\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#enabling-api-basic-auth","title":"Enabling api basic auth","text":"<p>Users enabling either the api or dashboard are encouraged to enable basic auth. This will apply only to the api/dashboard, and not to apps. To enable, set the <code>basic-auth-username</code> and <code>basic-auth-password</code> properties with the <code>--global</code> flag:. Both must be set or basic auth will not be enabled.</p> <pre><code>dokku traefik:set --global basic-auth-username username\ndokku traefik:set --global basic-auth-password password\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#customizing-the-api-hostname","title":"Customizing the api hostname","text":"<p>The hostname used for the api and dashboard is set to <code>traefik.dokku.me</code> by default. It can be customized by setting the <code>api-vhost</code> property with the <code>--global</code> flag:</p> <pre><code>dokku traefik:set --global api-vhost lb.dokku.me\n</code></pre> <p>After enabling, the Traefik container will need to be restarted.</p>"},{"location":"networking/proxies/traefik/#displaying-traefik-reports-for-an-app","title":"Displaying Traefik reports for an app","text":"<p>You can get a report about the app's Traefik config using the <code>traefik:report</code> command:</p> ShellOutput <pre><code>dokku traefik:report\n</code></pre> <pre><code>=====&gt; node-js-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n=====&gt; python-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n=====&gt; ruby-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku traefik:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app traefik information\n       Traefik api enabled:           false\n       Traefik api vhost:             traefik.dokku.me\n       Traefik basic auth password:   password\n       Traefik basic auth username:   user\n       Traefik dashboard enabled:     false\n       Traefik image:                 traefik:v2.8\n       Traefik letsencrypt email:\n       Traefik letsencrypt server:\n       Traefik log level:             ERROR\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku traefik:report node-js-app --traefik-api-enabled\n</code></pre>"},{"location":"processes/entering-containers/","title":"Entering containers","text":"<p>New</p> <p>Introduced in 0.4.0</p> <pre><code>enter &lt;app&gt;  [&lt;container-type&gt; || --container-id &lt;container-id&gt;]  # Connect to a specific app container\n</code></pre>"},{"location":"processes/entering-containers/#usage","title":"Usage","text":"<p>The <code>enter</code> command can be used to enter a running container. The following variations of the command exist:</p> <pre><code># enter the web process\ndokku enter node-js-app web\n\n# enter the first web process\ndokku enter node-js-app web.1\n\n# enter a process for an app by container ID\ndokku enter node-js-app --container-id ID\n</code></pre> <p>The <code>container-type</code> argument can be one either:</p> <ul> <li>If your app has a <code>Procfile</code>, the name of a process type in your <code>Procfile</code>.</li> <li>If your app has no <code>Procfile</code>, the word <code>web</code>.</li> </ul> <p>If the specified process type is scaled up to more than one container, then the first container will be automatically selected. this can be overriden by specifying an integer index denoting the desired container, where the first container's index is <code>1</code>.</p> <p>Additionally, the <code>enter</code> command can be executed with no <code>&lt;container-type&gt;</code>. If only a single <code>&lt;container-type&gt;</code> is defined in the app's Procfile, executing <code>enter</code> will drop the terminal into the only running container. This behavior is not supported when specifying a custom command; as described below.</p> <p>By default, <code>dokku enter</code> will run a <code>/bin/bash</code>, but can also be used to run custom commands:</p> <pre><code># just echo hi\ndokku enter node-js-app web echo hi\n\n# run a long-running command, as one might for a cron task\ndokku enter node-js-app web python script/background-worker.py\n</code></pre>"},{"location":"processes/one-off-tasks/","title":"One-off Tasks","text":"<pre><code>run [-e|--env KEY=VALUE] [--no-tty] &lt;app&gt; &lt;cmd&gt;              # Run a command in a new container using the current app image\nrun:detached [-e|-env KEY=VALUE] [--no-tty] &lt;app&gt; &lt;cmd&gt;      # Run a command in a new detached container using the current app image\nrun:list [--format json|stdout] [&lt;app&gt;]                      # List all run containers for an app\nrun:logs &lt;app|--container CONTAINER&gt; [-h] [-t] [-n num] [-q] # Display recent log output for run containers\nrun:stop &lt;app|--container CONTAINER&gt;                         # Stops all run containers for an app or a specified run container\n</code></pre> <p>Sometimes it is necessary to run a one-off command under an app. Dokku makes it easy to run a fresh container via the <code>run</code> command.</p>"},{"location":"processes/one-off-tasks/#usage","title":"Usage","text":""},{"location":"processes/one-off-tasks/#running-a-one-off-command","title":"Running a one-off command","text":"<p>The <code>run</code> command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container.  The container image will be the same container image as was used to start the currently deployed app.</p> <p>New</p> <p>Introduced in 0.25.0, this container will be removed after the process exits.</p> <pre><code># runs `ls -lah` in the `/app` directory of the app `node-js-app`\ndokku run node-js-app ls -lah\n\n# optionally, run can be passed custom environment variables\ndokku run --env \"NODE_ENV=development\" --env \"PATH=/custom/path\" node-js-app npm run mytask\n</code></pre> <p>One off containers are removed at the end of process execution.</p>"},{"location":"processes/one-off-tasks/#running-procfile-commands","title":"Running Procfile commands","text":"<p>The <code>run</code> command can also be used to run a command defined in the app <code>Procfile</code>:</p> <pre><code>console: bundle exec racksh\n</code></pre> <pre><code># runs `bundle exec racksh` in the `/app` directory of the app `my-app`\ndokku run my-app console\n</code></pre>"},{"location":"processes/one-off-tasks/#specifying-container-labels","title":"Specifying container labels","text":"<p>Containers may have specific labels attached. In order to avoid issues with dokku internals, do not use any labels beginning with either <code>com.dokku</code> or <code>org.label-schema</code>.</p> <pre><code>dokku --label=com.example.test-label=value run node-js-app ls -lah\n</code></pre>"},{"location":"processes/one-off-tasks/#disabling-tty","title":"Disabling TTY","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>One-off containers default to interactive mode where possible. To disable this behavior, specify the <code>--no-tty</code> flag:</p> <pre><code>dokku run --no-tty node-js-app ls -lah\n</code></pre>"},{"location":"processes/one-off-tasks/#running-a-detached-container","title":"Running a detached container","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>Finally, a container can be run in \"detached\" mode via the <code>run:detached</code> Dokku command. Running a process in detached mode will immediately return a <code>CONTAINER_ID</code>. Detached containers are run without a tty and are also removed at the end of process execution.</p> <pre><code>dokku run:detached node-js-app ls -lah\n# returns the ID of the new container\n</code></pre>"},{"location":"processes/one-off-tasks/#displaying-one-off-container-logs","title":"Displaying one-off container logs","text":"<p>You can easily get logs of all one-off containers for an app using the <code>logs</code> command:</p> <pre><code>dokku run:logs node-js-app\n</code></pre> <p>Logs are pulled via integration with the scheduler for the specified application via \"live tailing\". As such, logs from previously running deployments are usually not available. Users that desire to see logs from previous deployments for debugging purposes should persist those logs to external services. Please see Dokku's vector integration for more information on how to persist logs across deployments to ship logs to another service or a third-party platform.</p>"},{"location":"processes/one-off-tasks/#behavioral-modifiers","title":"Behavioral modifiers","text":"<p>Dokku also supports certain command-line arguments that augment the <code>run:log</code> command's behavior.</p> <pre><code>--container NAME     # the name of a specific container to show logs for\n-n, --num NUM        # the number of lines to display\n-t, --tail           # continually stream logs\n-q, --quiet          # display raw logs without colors, time and names\n</code></pre> <p>You can use these modifiers as follows:</p> <pre><code>dokku run:logs -t --container node-js-app.run.1234\n</code></pre> <p>The above command will show logs continually from the <code>node-js-app.run.1234</code> one-off run process.</p>"},{"location":"processes/one-off-tasks/#listing-one-off-containers","title":"Listing one-off containers","text":"<p>New</p> <p>Introduced in 0.25.0</p> <p>One-off containers for a given app can be listed via the <code>run:list</code> command:</p> ShellOutput <pre><code>dokku run:list node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app run containers\nNAMES                   COMMAND            CREATED\nnode-js-app.run.28689   \"/exec sleep 15\"   2 seconds ago\n</code></pre> <p>Info</p> <p>The <code>COMMAND</code> displayed will be what Docker executes and may not exactly match the command specified by a <code>dokku run</code> command.</p> <p>The output can also be shown in json format:</p> ShellOutput <pre><code>dokku run:list node-js-app --format json\n</code></pre> <pre><code>[\n  {\n    \"name\": \"node-js-app.run.28689\",\n    \"state\": \"running\",\n    \"command\": \"\\\"/exec 'sleep 15'\\\"\",\n    \"created_at\": \"2022-08-03 05:47:44 +0000 UTC\"\n  }\n]\n</code></pre>"},{"location":"processes/one-off-tasks/#stopping-a-one-off-container","title":"Stopping a one-off container","text":"<p>New</p> <p>Introduced in 0.29.0</p> <p>Run containers for an app can be stopped via the <code>run:stop</code> command. The output will be the container id.</p> ShellOutput <pre><code># start a container\n# the output will be something like: node-js-app.run.2313\ndokku run node-js-app sleep 300\n\n# stop the container\ndokku run:stop --container node-js-app.run.2313\n</code></pre> <pre><code>node-js-app.run.2313\n</code></pre> <p>All containers for a given app can be stopped by specifying the app name.</p> ShellOutput <pre><code>dokku run:stop node-js-app\n</code></pre> <pre><code>node-js-app.run.2313\nnode-js-app.run.574\n</code></pre>"},{"location":"processes/process-management/","title":"Process Management","text":"<p>New</p> <p>Introduced in 0.3.14, Enhanced in 0.7.0</p> <pre><code>ps:inspect &lt;app&gt;                                                  # Displays a sanitized version of docker inspect for an app\nps:rebuild [--parallel count] [--all|&lt;app&gt;]                       # Rebuilds an app from source\nps:report [&lt;app&gt;] [&lt;flag&gt;]                                        # Displays a process report for one or more apps\nps:restart [--parallel count] [--all|&lt;app&gt;]  [&lt;process-name&gt;]     # Restart an app\nps:restore [&lt;app&gt;]                                                # Start previously running apps e.g. after reboot\nps:scale [--skip-deploy] &lt;app&gt; &lt;proc&gt;=&lt;count&gt; [&lt;proc&gt;=&lt;count&gt;...] # Get/Set how many instances of a given process to run\nps:set &lt;app&gt; &lt;key&gt; &lt;value&gt;                                        # Set or clear a ps property for an app\nps:start [--parallel count] [--all|&lt;app&gt;]                         # Start an app\nps:stop [--parallel count] [--all|&lt;app&gt;]                          # Stop an app\n</code></pre>"},{"location":"processes/process-management/#usage","title":"Usage","text":""},{"location":"processes/process-management/#inspecting-app-containers","title":"Inspecting app containers","text":"<p>New</p> <p>Introduced in 0.13.0</p> <p>A common administrative task to perform is calling <code>docker inspect</code> on the containers that are running for an app. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the <code>ps:inspect</code> command:</p> <pre><code>dokku ps:inspect node-js-app\n</code></pre> <p>This command will gather all the running container IDs for your app and call <code>docker inspect</code>, sanitizing the output data so it can be copy-pasted elsewhere safely.</p>"},{"location":"processes/process-management/#rebuilding-apps","title":"Rebuilding apps","text":"<p>It may be useful to rebuild an app at will, such as for commands that do not rebuild an app or when skipping a rebuild after setting multiple config values. For these use cases, the <code>ps:rebuild</code> function can be used.</p> <pre><code>dokku ps:rebuild node-js-app\n</code></pre> <p>All apps may be rebuilt by using the <code>--all</code> flag.</p> <pre><code>dokku ps:rebuild --all\n</code></pre> <p>By default, rebuilding all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:rebuild --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:rebuild --all --parallel -1\n</code></pre> <p>A missing linked container will result in failure to boot apps. Services should all be started for apps being rebuilt.</p>"},{"location":"processes/process-management/#restarting-apps","title":"Restarting apps","text":"<p>An app may be restarted using the <code>ps:restart</code> command.</p> <pre><code>dokku ps:restart node-js-app\n</code></pre> <p>A single process type - such as <code>web</code> or <code>worker</code> - may also be specified. This does not support specifying a given instance of a process type, and only supports restarting all instances of that process type.</p> <pre><code>dokku ps:restart node-js-app web\n</code></pre> <p>All apps may be restarted by using the <code>--all</code> flag. This flag is incompatible with specifying a process type.</p> <pre><code>dokku ps:restart --all\n</code></pre> <p>By default, restarting all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:restart --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:restart --all --parallel -1\n</code></pre> <p>A missing linked container will result in failure to boot apps. Services should all be started for apps being rebuilt.</p>"},{"location":"processes/process-management/#displaying-existing-scale-properties","title":"Displaying existing scale properties","text":"<p>Issuing the <code>ps:scale</code> command with no arguments will output the current scaling properties for an app.</p> ShellOutput <pre><code>dokku ps:scale node-js-app\n</code></pre> <pre><code>-----&gt; Scaling for python\nproctype: qty\n--------: ---\nweb:  1\n</code></pre>"},{"location":"processes/process-management/#defining-processes","title":"Defining Processes","text":""},{"location":"processes/process-management/#procfile","title":"Procfile","text":"<p>Note</p> <p>Dokku supports the Procfile format as defined in this document under \"Strict Mode\" parsing rules.</p> <p>Apps can define processes to run by using a <code>Procfile</code>. A <code>Procfile</code> is a simple text file that can be used to specify multiple commands, each of which is subject to process scaling. In the case where the built image sets a default command to run - either through usage of <code>CMD</code> for Dockerfile-based builds, a default process for buildpack-based builds, or any other method for the builder in use - the <code>Procfile</code> will take precedence.</p> <p>If the file exists, it should not be empty, as doing so may result in a failed deploy.</p> <p>The syntax for declaring a <code>Procfile</code> is as follows. Note that the format is one process type per line, with no duplicate process types.</p> <pre><code>&lt;process type&gt;: &lt;command&gt;\n</code></pre> <p>If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types:</p> <pre><code>worker:           env QUEUE=* bundle exec rake resque:work\nimportantworker:  env QUEUE=important bundle exec rake resque:work\n</code></pre> <p>If the app build declares an <code>ENTRYPOINT</code>, the command defined in the <code>Procfile</code> is passed as an argument to that entrypoint. This is the case for all Dockerfile-based, Docker Image, and Cloud Native Buildpack deployments.</p> <p>The <code>web</code> process type holds some significance in that it is the only process type that is automatically scaled to <code>1</code> on the initial application deploy. See the web process scaling documentation for more details around scaling individual processes.</p> <p>See the Procfile location documentation for more information on where to place your <code>Procfile</code> file.</p>"},{"location":"processes/process-management/#the-web-process","title":"The <code>web</code> process","text":"<p>For initial app deploys, Dokku will default to starting a single <code>web</code> process for each app. This process may be defined within the <code>Procfile</code> or as the <code>CMD</code> (for Dockerfile or Docker image deploys). Scaling of the <code>web</code> process - and all other processes - may be managed via <code>ps:scale</code> or the <code>formation</code> key in the <code>app.json</code> file either before or after the initial deploy.</p> <p>There are also a few other exceptions for the <code>web</code> process.</p> <ul> <li>By default, the built-in nginx proxy implementation only proxies the <code>web</code> process (others may be handled via a custom <code>nginx.conf.sigil</code>).<ul> <li>See the nginx request proxying documentation for more information on how nginx handles proxied requests.</li> </ul> </li> <li>Only the <code>web</code> process may be bound to an external port.</li> </ul>"},{"location":"processes/process-management/#the-release-process","title":"The <code>release</code> process","text":"<p>The <code>Procfile</code> also supports a special <code>release</code> command which acts in a similar way to the Heroku Release Phase. See the Release deployment task documentation for more information on how Dokku handles this process type.</p>"},{"location":"processes/process-management/#changing-the-procfile-location","title":"Changing the <code>Procfile</code> location","text":"<p>When deploying a monorepo, it may be desirable to specify the specific path of the <code>Procfile</code> file to use for a given app. This can be done via the <code>ps:set</code> command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no <code>Procfile</code>.</p> <p>For deploys via the <code>git:from-image</code> and <code>git:load-image</code> commands, the <code>Procfile</code> is extracted from the configured <code>WORKDIR</code> property of the image. For all other deploys - git push, <code>git:from-archive</code>, <code>git:sync</code> - will have the <code>Procfile</code> extracted directly from the source code. Both cases will respect the configured <code>procfile-path</code> property value.</p> <pre><code>dokku ps:set node-js-app procfile-path .dokku/Procfile\n</code></pre> <p>The default value may be set by passing an empty value for the option:</p> <pre><code>dokku ps:set node-js-app procfile-path\n</code></pre> <p>The <code>procfile-path</code> property can also be set globally. The global default is <code>Procfile</code>, and the global value is used when no app-specific value is set.</p> <pre><code>dokku ps:set --global procfile-path global-Procfile\n</code></pre> <p>The default value may be set by passing an empty value for the option.</p> <pre><code>dokku ps:set --global procfile-path\n</code></pre>"},{"location":"processes/process-management/#scaling-apps","title":"Scaling apps","text":""},{"location":"processes/process-management/#via-cli","title":"Via CLI","text":"<p>Info</p> <p>This functionality is disabled if the formation is managed via the <code>formation</code> key of <code>app.json</code>.</p> <p>Dokku can also manage scaling itself via the <code>ps:scale</code> command. This command can be used to scale multiple process types at the same time.</p> <pre><code>dokku ps:scale node-js-app web=1\n</code></pre> <p>Multiple process types can be scaled at once:</p> <pre><code>dokku ps:scale node-js-app web=1 worker=1\n</code></pre> <p>If desired, the corresponding deploy will be skipped by using the <code>--skip-deploy</code> flag:</p> <pre><code>dokku ps:scale --skip-deploy node-js-app web=1\n</code></pre>"},{"location":"processes/process-management/#manually-managing-process-scaling","title":"Manually managing process scaling","text":"<p>Info</p> <p>Using a <code>formation</code> key in an <code>app.json</code> file with any <code>quantity</code> specified disables the ability to use <code>ps:scale</code> for scaling. All processes not specified in the <code>app.json</code> will have their process count set to zero.</p> <p>Users can also configure scaling within the codebase itself to manage process scaling. The <code>formation</code> key should be specified as follows in the <code>app.json</code> file:</p> <pre><code>{\n  \"formation\": {\n    \"web\": {\n      \"quantity\": 1\n    },\n    \"worker\": {\n      \"quantity\": 4\n    }\n  }\n}\n</code></pre> <p>Removing the <code>formation</code> key or removing the <code>app.json</code> file from your repository will result in Dokku respecting the <code>ps:scale</code> command for setting scale values. The values set via the <code>app.json</code> file from a previous deploy will be respected.</p> <p>See the app.json location documentation for more information on where to place your <code>app.json</code> file.</p>"},{"location":"processes/process-management/#stopping-apps","title":"Stopping apps","text":"<p>Deployed apps can be stopped using the <code>ps:stop</code> command. This turns off all running containers for an app, and will result in a 502 Bad Gateway response for the default nginx proxy implementation.</p> <pre><code>dokku ps:stop node-js-app\n</code></pre> <p>All apps may be stopped by using the <code>--all</code> flag.</p> <pre><code>dokku ps:stop --all\n</code></pre> <p>By default, stopping all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:stop --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:stop --all --parallel -1\n</code></pre>"},{"location":"processes/process-management/#starting-apps","title":"Starting apps","text":"<p>All stopped containers can be started using the <code>ps:start</code> command. This is similar to running <code>ps:restart</code>, except no action will be taken if the app containers are running.</p> <pre><code>dokku ps:start node-js-app\n</code></pre> <p>All apps may be started by using the <code>--all</code> flag.</p> <pre><code>dokku ps:start --all\n</code></pre> <p>By default, starting all apps happens serially. The parallelism may be controlled by the <code>--parallel</code> flag.</p> <pre><code>dokku ps:start --all --parallel 2\n</code></pre> <p>Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the <code>--parallel</code> flag to <code>-1</code></p> <pre><code>dokku ps:start --all --parallel -1\n</code></pre>"},{"location":"processes/process-management/#restart-policies","title":"Restart policies","text":"<p>New</p> <p>Introduced in 0.7.0, Command Changed in 0.22.0</p> <p>By default, Dokku will automatically restart containers that exit with a non-zero status up to 10 times via the on-failure Docker restart policy.</p>"},{"location":"processes/process-management/#setting-the-restart-policy","title":"Setting the restart policy","text":"<p>Info</p> <p>A change in the restart policy must be followed by a <code>ps:rebuild</code> call.</p> <p>You can configure this via the <code>ps:set</code> command:</p> <pre><code># always restart an exited container\ndokku ps:set node-js-app restart-policy always\n\n# never restart an exited container\ndokku ps:set node-js-app restart-policy no\n\n# only restart it on Docker restart if it was not manually stopped\ndokku ps:set node-js-app restart-policy unless-stopped\n\n# restart only on non-zero exit status\ndokku ps:set node-js-app restart-policy on-failure\n\n# restart only on non-zero exit status up to 20 times\ndokku ps:set node-js-app restart-policy on-failure:20\n</code></pre> <p>Restart policies have no bearing on server reboot, and Dokku will always attempt to restart your apps at that point unless they were manually stopped.</p> <p>Dokku also runs <code>dokku-event-listener</code> in the background via the system's init service. This monitors container state, performing the following actions:</p> <ul> <li>If a web process restarts and it's container IP address changes, the app's proxy configuration will be rebuilt.</li> <li>If a process within an app exceeds the restart count, the app will be rebuilt.</li> </ul>"},{"location":"processes/process-management/#displaying-reports-for-an-app","title":"Displaying reports for an app","text":"<p>New</p> <p>Introduced in 0.12.0</p> <p>You can get a report about the deployed apps using the <code>ps:report</code> command:</p> ShellOutput <pre><code>dokku ps:report\n</code></pre> <pre><code>=====&gt; node-js-app ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps computed procfile path:     Procfile2\n       Ps global procfile path:       Procfile\n       Ps restart policy:             on-failure:10\n       Ps procfile path:              Procfile2\n       Restore:                       true\n       Running:                       false\n=====&gt; python-sample ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps computed procfile path:     Procfile\n       Ps global procfile path:       Procfile\n       Ps restart policy:             on-failure:10\n       Ps procfile path:\n       Restore:                       true\n       Running:                       false\n=====&gt; ruby-sample ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps computed procfile path:     Procfile\n       Ps global procfile path:       Procfile\n       Ps restart policy:             on-failure:10\n       Ps procfile path:\n       Restore:                       true\n       Running:                       false\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku ps:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app ps information\n       Deployed:                      false\n       Processes:                     0\n       Ps can scale:                  true\n       Ps restart policy:             on-failure:10\n       Restore:                       true\n       Running:                       false\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku ps:report node-js-app --deployed\n</code></pre>"},{"location":"processes/process-management/#restoring-apps-after-a-server-reboot","title":"Restoring apps after a server reboot","text":"<p>When a server reboots or Docker is restarted/upgraded, Docker may or may not start old app containers automatically, and may in some cases re-assign container IP addresses. To combat this issue, Dokku uses an init process that triggers <code>dokku ps:restore</code> after the Docker daemon is detected as starting. When triggered, the <code>dokku ps:restore</code> command will serially (one by one) run the following for each:</p> <ul> <li>Start all linked services.</li> <li>Clear generated proxy configuration files.</li> <li>Start the app if it has not been manually stopped.<ul> <li>If the app containers still exist, they will be started and the generated proxy configuration files will be rebuilt.</li> <li>If any of the app containers are missing, the entire app will be rebuilt.</li> </ul> </li> </ul> <p>During this time, requests may route to the incorrect app if the assigned IPs correspond to those for other apps. While dokku makes all efforts to avoid this, there may be a few minutes where urls may route to the wrong app. To avoid this, either use a custom proxy plugin or wait a few minutes until the restoration process is complete.</p>"},{"location":"processes/scheduled-cron-tasks/","title":"Scheduled Cron Tasks","text":"<p>New</p> <p>Introduced in 0.23.0</p> <pre><code>cron:list &lt;app&gt; [--format json|stdout] # List scheduled cron tasks for an app\ncron:report [&lt;app&gt;] [&lt;flag&gt;]           # Display report about an app\ncron:run &lt;app&gt; &lt;cron_id&gt; [--detach]    # Run a cron task on the fly\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#usage","title":"Usage","text":""},{"location":"processes/scheduled-cron-tasks/#dokku-managed-cron","title":"Dokku Managed Cron","text":"<p>Dokku automates scheduled <code>dokku run</code> commands via it's <code>app.json</code> cron integration.</p>"},{"location":"processes/scheduled-cron-tasks/#specifying-commands","title":"Specifying commands","text":"<p>The <code>app.json</code> file for a given app can define a special <code>cron</code> key that contains a list of commands to run on given schedules. The following is a simple example <code>app.json</code> that effectively runs the command <code>dokku run $APP npm run send-email</code> once a day:</p> <pre><code>{\n  \"cron\": [\n    {\n      \"command\": \"npm run send-email\",\n      \"schedule\": \"@daily\"\n    }\n  ]\n}\n</code></pre> <p>A cron entry takes the following properties:</p> <ul> <li><code>command</code>: A command to be run within the built app image. Specified commands can also be <code>Procfile</code> entries.</li> <li><code>schedule</code>: A cron-compatible scheduling definition upon which to run the command. Seconds are generally not supported.</li> </ul> <p>Zero or more cron commands can be specified per app. Cron entries are validated after the build artifact is created but before the app is deployed, and the cron schedule is updated during the post-deploy phase.</p> <p>See the app.json location documentation for more information on where to place your <code>app.json</code> file.</p>"},{"location":"processes/scheduled-cron-tasks/#task-environment","title":"Task Environment","text":"<p>When running scheduled cron tasks, there are a few items to be aware of:</p> <ul> <li>Scheduled cron tasks are performed within the app environment available at runtime. If the app image does not exist, the command may fail to execute.</li> <li>Schedules are performed on the hosting server's timezone, which is typically UTC.</li> <li>At this time, only the <code>PATH</code> and <code>SHELL</code> environment variables are specified in the cron template.<ul> <li>A <code>MAILTO</code> value can be set via the <code>cron:set</code> command.</li> </ul> </li> <li>Each scheduled task is executed within a one-off <code>run</code> container, and thus inherit any docker-options specified for <code>run</code> containers. Resources are never shared between scheduled tasks.</li> <li>Scheduled cron tasks are supported on a per-scheduler basis, and are currently only implemented by the <code>docker-local</code> scheduler.</li> <li>Tasks for all apps managed by the <code>docker-local</code> scheduler are written to a single crontab file owned by the <code>dokku</code> user. The <code>dokku</code> user's crontab should be considered reserved for this purpose.</li> </ul>"},{"location":"processes/scheduled-cron-tasks/#specifying-a-mailto-value","title":"Specifying a MAILTO value","text":"<p>By default, cron tasks complete and do not perform any reporting. Users can specify a value for <code>MAILTO</code> via the global <code>mailto</code> cron property by using the <code>cron:set</code> command.</p> <pre><code>dokku cron:set --global mailto example@example.com\n</code></pre> <p>All output for individual cron runs will be sent to the specified email.</p> <p>Cron emails can be disabled by running the <code>cron:set</code> command for the global <code>mailto</code> property with no value.</p> <pre><code>dokku cron:set --global mailto\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#listing-cron-tasks","title":"Listing Cron tasks","text":"<p>Cron tasks for an app can be listed via the <code>cron:list</code> command. This command takes an <code>app</code> argument.</p> ShellOutput <pre><code>dokku cron:list node-js-app\n</code></pre> <pre><code>ID                                    Schedule   Command\ncGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5  @daily     node index.js\ncGhwPT09dHJ1ZT09PSogKiAqICogKg==      * * * * *  true\n</code></pre> <p>The output can also be displayed in json format:</p> ShellOutput <pre><code>dokku cron:list node-js-app --format json\n</code></pre> <pre><code>[{\"id\":\"cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5\",\"app\":\"node-js-app\",\"command\":\"node index.js\",\"schedule\":\"@daily\"}]\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#executing-a-cron-task-on-the-fly","title":"Executing a cron task on the fly","text":"<p>Cron tasks can be invoked via the <code>cron:run</code> command. This command takes an <code>app</code> argument and a <code>cron id</code> (retrievable from <code>cron:list</code> output).</p> <pre><code>dokku cron:run node-js-app cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5\n</code></pre> <p>By default, the task is run in an attached container - as supported by the scheduler. To run in a background detached container, specify the <code>--detach</code> flag:</p> <pre><code>dokku cron:run node-js-app cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5 --detach\n</code></pre> <p>All one-off cron executions have their containers terminated after invocation.</p>"},{"location":"processes/scheduled-cron-tasks/#displaying-reports","title":"Displaying reports","text":"<p>You can get a report about the cron configuration for apps using the <code>cron:report</code> command:</p> ShellOutput <pre><code>dokku cron:report\n</code></pre> <pre><code>=====&gt; node-js-app cron information\n       Cron task count:               2\n=====&gt; python-sample cron information\n       Cron task count:               0\n=====&gt; ruby-sample cron information\n       Cron task count:               10\n</code></pre> <p>You can run the command for a specific app also.</p> ShellOutput <pre><code>dokku cron:report node-js-app\n</code></pre> <pre><code>=====&gt; node-js-app cron information\n       Cron task count:               2\n</code></pre> <p>You can pass flags which will output only the value of the specific information you want. For example:</p> <pre><code>dokku cron:report node-js-app --cron-task-count\n</code></pre>"},{"location":"processes/scheduled-cron-tasks/#self-managed-cron","title":"Self Managed Cron","text":"<p>Warning</p> <p>Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary.</p> <p>Some installations may require more fine-grained control over cron usage. The following are advanced instructions for configuring cron.</p>"},{"location":"processes/scheduled-cron-tasks/#using-run-for-cron-tasks","title":"Using <code>run</code> for cron tasks","text":"<p>You can always use a one-off container to run an app task:</p> <pre><code>dokku run node-js-app some-command\n</code></pre> <p>For tasks that should not be interrupted, run is the preferred method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.</p>"},{"location":"processes/scheduled-cron-tasks/#using-enter-for-cron-tasks","title":"Using <code>enter</code> for cron tasks","text":"<p>Your Procfile can have the following entry:</p> <pre><code>cron: sleep infinity\n</code></pre> <p>With the <code>cron</code> process scaled to <code>1</code>:</p> <pre><code>dokku ps:scale node-js-app cron=1\n</code></pre> <p>You can now run all your commands in that container:</p> <pre><code>dokku enter node-js-app cron some-command\n</code></pre> <p>Note that you can also run multiple commands at the same time to reduce memory usage, though that may result in polluting the container environment.</p> <p>For tasks that will properly resume, you should use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.</p>"},{"location":"processes/scheduled-cron-tasks/#general-cron-recommendations","title":"General cron recommendations","text":"<p>Regularly scheduled tasks can be a bit of a pain with Dokku. The following are general recommendations to follow to help ensure successful task runs.</p> <ul> <li>Use the <code>dokku</code> user in your cron entry.<ul> <li>If you do not, the <code>dokku</code> binary will attempt to execute with <code>sudo</code>, and your cron run with fail with <code>sudo: no tty present and no askpass program specified</code>.</li> </ul> </li> <li>Add a <code>MAILTO</code> environment variable to ship cron emails to yourself.</li> <li>Add a <code>PATH</code> environment variable or specify the full path to binaries on the host.</li> <li>Add a <code>SHELL</code> environment variable to specify Bash when running commands.</li> <li>Keep your cron tasks in time-sorted order.</li> <li>Keep your server time in UTC so you don't need to translate daylight savings time when reading the cronfile.</li> <li>Run tasks at the lowest traffic times if possible.</li> <li>Use cron to trigger jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.</li> <li>Try to keep tasks quiet so that mails only send on errors.</li> <li>Do not silence standard error or standard out. If you silence the former, you will miss failures. Silencing the latter means you should actually make app changes to handle log levels.</li> <li>Use a service such as Dead Man's Snitch to verify that cron tasks completed successfully.</li> <li>Add lots of comments to your cronfile, including what a task is doing, so that you don't spend time deciphering the file later.</li> <li>Place your cronfiles in a pattern such as <code>/etc/cron.d/APP</code>.</li> <li>Do not use non-ASCII characters in your cronfile names. cron is finicky.</li> <li>Remember to have trailing newlines in your cronfile! cron is finicky.</li> </ul> <p>The following is a sample cronfile that you can use for your apps:</p> <pre><code># server cron jobs\nMAILTO=\"mail@dokku.me\"\nPATH=/usr/local/bin:/usr/bin:/bin\nSHELL=/bin/bash\n\n# m   h   dom mon dow   username command\n# *   *   *   *   *     dokku    command to be executed\n# -   -   -   -   -\n# |   |   |   |   |\n# |   |   |   |   +----- day of week (0 - 6) (Sunday=0)\n# |   |   |   +------- month (1 - 12)\n# |   |   +--------- day of month (1 - 31)\n# |   +----------- hour (0 - 23)\n# +----------- min (0 - 59)\n\n### HIGH TRAFFIC TIME IS B/W 00:00 - 04:00 AND 14:00 - 23:59\n### RUN YOUR TASKS FROM 04:00 - 14:00\n### KEEP SORTED IN TIME ORDER\n\n### PLACE ALL CRON TASKS BELOW\n\n# removes unresponsive users from the subscriber list to decrease bounce rates\n0 0 * * * dokku dokku run node-js-app some-command\n\n# sends out our email alerts to users\n0 1 * * * dokku dokku ps:scale node-js-app cron=1 &amp;&amp; dokku enter node-js-app cron some-other-command &amp;&amp; dokku ps:scale node-js-app cron=0\n\n### PLACE ALL CRON TASKS ABOVE, DO NOT REMOVE THE WHITESPACE AFTER THIS LINE\n</code></pre>"}]}
\ No newline at end of file
diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz
index 9a69ba060..843257c66 100644
Binary files a/docs/sitemap.xml.gz and b/docs/sitemap.xml.gz differ