mirror of
https://github.com/dokku/dokku.git
synced 2025-12-29 00:25:08 +01:00
Merge pull request #2295 from dokku/more-docs
Add documentation for the apps, repo, and tar plugin
This commit is contained in:
Jose Diaz-Gonzalez
34
docs/advanced-usage/repository-management.md
Normal file
34
docs/advanced-usage/repository-management.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Repository Management
|
||||
|
||||
> New as of 0.6.0
|
||||
|
||||
```
|
||||
repo:gc <app> # Runs 'git gc --agressive' against the application's repo
|
||||
repo:purge-cache <app> # Deletes the contents of the build cache stored in the repository
|
||||
```
|
||||
|
||||
The repository plugin is meant to allow users to perform management commands against a repository.
|
||||
|
||||
# Git Garbage Collection
|
||||
|
||||
This will run a git gc --agressive against the applications repo. This is performed on the Dokku host, and not within an application container.
|
||||
|
||||
```shell
|
||||
dokku repo:gc node-js-app
|
||||
```
|
||||
|
||||
```
|
||||
Counting objects: 396, done.
|
||||
Delta compression using up to 2 threads.
|
||||
Compressing objects: 100% (365/365), done.
|
||||
Writing objects: 100% (396/396), done.
|
||||
Total 396 (delta 79), reused 315 (delta 0)
|
||||
```
|
||||
|
||||
## Clearing Application cache
|
||||
|
||||
Building containers with buildpacks currently results in a persistent `cache` directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command:
|
||||
|
||||
```shell
|
||||
dokku repo:purge-cache node-js-app
|
||||
```
|
||||
@@ -20,6 +20,6 @@
|
||||
|
||||
## Dockerfile apps with exposed ports
|
||||
|
||||
- Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/dokku/deployment/dockerfiles/#exposed-ports)
|
||||
- Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/dokku/deployment/methods/dockerfiles/#exposed-ports)
|
||||
- Note that nginx will proxy the same port numbers to listen publicly
|
||||
- UDP ports can be exposed by disabling the [nginx proxy](/dokku/advanced-usage/proxy-management/) with `dokku proxy:disable myapp`
|
||||
|
||||
@@ -85,36 +85,6 @@ When the deploy finishes, the application's URL will be shown as seen above.
|
||||
|
||||
Dokku supports deploying applications via [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) with [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks) or using a project's [dockerfile](https://docs.docker.com/reference/builder/).
|
||||
|
||||
### Removing a deployed app
|
||||
|
||||
You can also remove an application from your Dokku installation. This 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).
|
||||
|
||||
```shell
|
||||
# on your dokku host
|
||||
# replace APP with the name of your application
|
||||
dokku apps:destroy APP
|
||||
```
|
||||
|
||||
This will prompt you to verify the application's name before destroying it. You may also use the `--force` flag to circumvent this verification process:
|
||||
|
||||
```shell
|
||||
# on your dokku host
|
||||
# replace APP with the name of your application
|
||||
dokku --force apps:destroy APP
|
||||
```
|
||||
|
||||
### Renaming a deployed app
|
||||
|
||||
> New as of 0.4.7
|
||||
|
||||
You can rename a deployed app using the `apps:rename` CLI tool:
|
||||
|
||||
```shell
|
||||
# on your dokku host
|
||||
dokku apps:rename OLD_NAME NEW_NAME
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Deploying non-master branch
|
||||
|
||||
@@ -198,15 +168,23 @@ See the [nginx documentation](/dokku/configuration/nginx/#default-site).
|
||||
|
||||
## Dockerfile deployment
|
||||
|
||||
See the [dockerfile documentation](/dokku/deployment/dockerfiles/).
|
||||
See the [dockerfile documentation](/dokku/deployment/methods/dockerfiles/).
|
||||
|
||||
## Specifying a custom buildpack
|
||||
|
||||
See the [buildpack documentation](/dokku/deployment/buildpacks/).
|
||||
See the [buildpack documentation](/dokku/deployment/methods/buildpacks/).
|
||||
|
||||
## Image tagging
|
||||
|
||||
See the [image tagging documentation](/dokku/deployment/images/).
|
||||
See the [image tagging documentation](/dokku/deployment/methods/images/).
|
||||
|
||||
## Removing a deployed app
|
||||
|
||||
See the [application management documentation](/dokku/deployment/application-management/#removing-a-deployed-app).
|
||||
|
||||
### Renaming a deployed app
|
||||
|
||||
See the [application management documentation](/dokku/deployment/application-management/#renaming-a-deployed-app).
|
||||
|
||||
## Zero downtime deploy
|
||||
|
||||
|
||||
110
docs/deployment/application-management.md
Normal file
110
docs/deployment/application-management.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Application Management
|
||||
|
||||
> New as of 0.3.1
|
||||
|
||||
```
|
||||
apps # List your apps
|
||||
apps:create <app> # Create a new app
|
||||
apps:destroy <app> # Permanently destroy an app
|
||||
apps:rename <old-app> <new-app> # Rename an app
|
||||
```
|
||||
|
||||
You can easily list all available applications using the `apps` command:
|
||||
|
||||
```shell
|
||||
dokku apps
|
||||
```
|
||||
|
||||
```
|
||||
=====> My Apps
|
||||
node-js-sample
|
||||
python-sample
|
||||
```
|
||||
|
||||
Note that you can easily hide extra output from dokku commands by using the `--quiet` flag, which makes it easier to parse on the command-line.
|
||||
|
||||
```shell
|
||||
dokku --quiet apps
|
||||
```
|
||||
|
||||
```
|
||||
node-js-sample
|
||||
python-sample
|
||||
```
|
||||
|
||||
## Manually creating an application
|
||||
|
||||
A common pattern for deploying applications to Dokku is to configure an application before deploying it. You can do so via the `apps:create` command:
|
||||
|
||||
```shell
|
||||
dokku apps:create node-js-app
|
||||
```
|
||||
|
||||
```
|
||||
Creating node-js-app... done
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
- configure domain names and ssl certificates
|
||||
- create and link datastores
|
||||
- set environment variables
|
||||
|
||||
## Removing a deployed app
|
||||
|
||||
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 `apps:destroy` 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.
|
||||
|
||||
```shell
|
||||
dokku apps:destroy node-js-app
|
||||
```
|
||||
|
||||
```
|
||||
! WARNING: Potentially Destructive Action
|
||||
! This command will destroy node-js-app (including all add-ons).
|
||||
! To proceed, type "node-js-app"
|
||||
|
||||
> node-js-app
|
||||
Destroying node-js-app (including all add-ons)
|
||||
```
|
||||
|
||||
This will prompt you to verify the application's name before destroying it. You may also use the `--force` flag to circumvent this verification process:
|
||||
|
||||
```shell
|
||||
dokku --force apps:destroy node-js-app
|
||||
```
|
||||
|
||||
```
|
||||
Destroying node-js-app (including all add-ons)
|
||||
```
|
||||
|
||||
|
||||
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).
|
||||
|
||||
## Renaming a deployed app
|
||||
|
||||
> New as of 0.4.7
|
||||
|
||||
You can rename a deployed app using the `apps:rename` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully:
|
||||
|
||||
```shell
|
||||
dokku apps:rename node-js-app io-js-app
|
||||
```
|
||||
|
||||
```
|
||||
Destroying node-js-app (including all add-ons)
|
||||
-----> Cleaning up...
|
||||
-----> Building io-js-app from herokuish...
|
||||
-----> Adding BUILD_ENV to build environment...
|
||||
-----> Node.js app detected
|
||||
|
||||
-----> Creating runtime environment
|
||||
|
||||
...
|
||||
|
||||
=====> Application deployed:
|
||||
http://io-js-app.ci.dokku.me
|
||||
|
||||
Renaming node-js-app to io-js-app... done
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -82,15 +82,6 @@ importantworker: env QUEUE=important bundle exec rake resque:work
|
||||
|
||||
The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/dokku/deployment/process-management/) for more details around scaling individual processes.
|
||||
|
||||
## Clearing buildpack cache
|
||||
|
||||
Building containers with buildpacks currently results in a persistent `cache` directory between deploys. If you need to clear this cache directory for any reason, you may do so by running the following shell command:
|
||||
|
||||
```shell
|
||||
# replace APP with the name of your application
|
||||
sudo rm -rf /home/dokku/APP/cache/*
|
||||
```
|
||||
|
||||
## Curl Build Timeouts
|
||||
|
||||
Certain buildpacks may time out in retrieving dependencies via curl. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a curl command.
|
||||
@@ -101,3 +92,7 @@ If you see output similar this when deploying , you may need to override the cur
|
||||
dokku config:set --global CURL_TIMEOUT=600
|
||||
dokku config:set --global CURL_CONNECT_TIMEOUT=30
|
||||
```
|
||||
|
||||
## Clearing buildpack cache
|
||||
|
||||
See the [repository management documentation](/dokku/advanced-usage/repository-management/#clearing-app-cache).
|
||||
@@ -1,4 +1,4 @@
|
||||
# Image Tagging
|
||||
# Image Tag Deployment
|
||||
|
||||
> New as of 0.4.0
|
||||
|
||||
25
docs/deployment/methods/tar.md
Normal file
25
docs/deployment/methods/tar.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Tarfile Deployment
|
||||
|
||||
> New as of 0.4.0
|
||||
|
||||
```
|
||||
tar:from <app> <url> # Loads an app tarball from url
|
||||
tar:in <app> # Reads an tarball containing the app from stdin
|
||||
```
|
||||
|
||||
## Deploying from a tarball
|
||||
|
||||
In some cases, it may be useful to deploy an application from a tarball. For instance, if you implemented a non-git based deployment plugin, tarring the generated artifact may be an easier route to interface with the existing dokku infrastructure.
|
||||
|
||||
You can place the tarball on an external webserver and deploy via the `tar:from` command.
|
||||
|
||||
```shell
|
||||
dokku tar:from node-js-app https://dokku.me/releases/node-js-app/v1
|
||||
```
|
||||
|
||||
As an alternative, a deploy can be trigged from a tarball read from stdin using the `tar:in` command:
|
||||
|
||||
```shell
|
||||
# run from the generated artifact directory
|
||||
tar c . $* | dokku tar:in node-js-app
|
||||
```
|
||||
@@ -5,7 +5,7 @@ Sometimes you need to either inspect running containers or run a one-off command
|
||||
## Run a command in an app environment
|
||||
|
||||
```
|
||||
run <app> <cmd> Run a command in the environment of an application
|
||||
run <app> <cmd> # Run a command in the environment of an application
|
||||
```
|
||||
|
||||
The `run` 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. Note that this container will be stay around even after command completes. The container will be the same container as was used to start the currently deployed application.
|
||||
@@ -68,7 +68,7 @@ For tasks that should not be interrupted, run is the **preferred** method of han
|
||||
> New as of 0.4.0
|
||||
|
||||
```
|
||||
enter <app> [<container-type> || --container-id <container-id>] Connect to a specific app container
|
||||
enter <app> [<container-type> || --container-id <container-id>] # Connect to a specific app container
|
||||
```
|
||||
|
||||
The `enter` command can be used to enter a running container. The following variations of the command exist:
|
||||
|
||||
@@ -9,10 +9,10 @@ Users in dokku are managed via the `~/dokku/.ssh/authorized_keys` file. While yo
|
||||
Dokku uses the [`sshcommand`](https://github.com/dokku/sshcommand) utility to manage ssh keys for the dokku user. The following is the usage output for sshcommand.
|
||||
|
||||
```
|
||||
sshcommand create <user> <command> # creates a user forced to run command when SSH connects
|
||||
sshcommand acl-add <user> <ssh-key-name> # adds named SSH key to user from STDIN
|
||||
sshcommand acl-remove <user> <ssh-key-name> # removes SSH key by name
|
||||
sshcommand help # displays the usage help message
|
||||
sshcommand create <user> <command> # creates a user forced to run command when SSH connects
|
||||
sshcommand acl-add <user> <ssh-key-name> # adds named SSH key to user from STDIN
|
||||
sshcommand acl-remove <user> <ssh-key-name> # removes SSH key by name
|
||||
sshcommand help # displays the usage help message
|
||||
```
|
||||
|
||||
In dokku's case, the `<user>` section is *always* `dokku`, as this is the system user that the dokku binary performs all it's actions. Keys are given unique names, which can be used in conjunction with the [user-auth](/dokku/development/plugin-triggers/#user-auth) plugin trigger to handle command authorization.
|
||||
|
||||
@@ -3,10 +3,10 @@
|
||||
> New as of 0.5.0
|
||||
|
||||
```
|
||||
checks <app> # Show zero-downtime status
|
||||
checks:disable <app> [process-type(s)] # Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments***
|
||||
checks:enable <app> [process-type(s)] # Enable zero-downtime deployment for all processes (or comma-separated process-type list)
|
||||
checks:skip <app> [process-type(s)] # Skip zero-downtime checks for all processes (or comma-separated process-type list)
|
||||
checks <app> # Show zero-downtime status
|
||||
checks:disable <app> [process-type(s)] # Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments***
|
||||
checks:enable <app> [process-type(s)] # Enable zero-downtime deployment for all processes (or comma-separated process-type list)
|
||||
checks:skip <app> [process-type(s)] # Skip zero-downtime checks for all processes (or comma-separated process-type list)
|
||||
```
|
||||
|
||||
Following a deploy, dokku will wait `10` seconds before routing traffic to the new container to give your application time to boot up. If the application is not running after this time, then the deploy is failed and your old container will continue serving traffic. You can modify this value globally or on a per-application basis:
|
||||
|
||||
@@ -131,15 +131,20 @@
|
||||
<a href="#" class="list-group-item disabled">Deployment</a>
|
||||
|
||||
<a href="/{{NAME}}/deployment/application-deployment/" class="list-group-item">Deploying an Application</a>
|
||||
<a href="/{{NAME}}/deployment/buildpacks/" class="list-group-item">Buildpack Deployment</a>
|
||||
<a href="/{{NAME}}/deployment/dockerfiles/" class="list-group-item">Dockerfile Deployment</a>
|
||||
<a href="/{{NAME}}/deployment/images/" class="list-group-item">Image Tagging</a>
|
||||
<a href="/{{NAME}}/deployment/application-management/" class="list-group-item">Application Management</a>
|
||||
<a href="/{{NAME}}/deployment/remote-commands/" class="list-group-item">Remote Commands</a>
|
||||
<a href="/{{NAME}}/deployment/one-off-processes/" class="list-group-item">One Off Processes/Cron</a>
|
||||
<a href="/{{NAME}}/deployment/process-management/" class="list-group-item">Scaling Apps</a>
|
||||
<a href="/{{NAME}}/deployment/user-management/" class="list-group-item">User Management</a>
|
||||
<a href="/{{NAME}}/deployment/zero-downtime-deploys/" class="list-group-item">Zero Downtime Deploy Checks</a>
|
||||
|
||||
<a href="#" class="list-group-item disabled">Deployment Methods</a>
|
||||
|
||||
<a href="/{{NAME}}/deployment/methods/buildpacks/" class="list-group-item">Buildpack Deployment</a>
|
||||
<a href="/{{NAME}}/deployment/methods/dockerfiles/" class="list-group-item">Dockerfile Deployment</a>
|
||||
<a href="/{{NAME}}/deployment/methods/images/" class="list-group-item">Docker Image Deployment</a>
|
||||
<a href="/{{NAME}}/deployment/methods/tar/" class="list-group-item">Tarfile Deployment</a>
|
||||
|
||||
<a href="#" class="list-group-item disabled">Configuration</a>
|
||||
|
||||
<a href="/{{NAME}}/configuration/environment-variables/" class="list-group-item">Environment Variables</a>
|
||||
@@ -156,6 +161,7 @@
|
||||
<a href="/{{NAME}}/advanced-usage/event-logs/" class="list-group-item">Event Logs</a>
|
||||
<a href="/{{NAME}}/advanced-usage/persistent-storage/" class="list-group-item">Persistent Storage</a>
|
||||
<a href="/{{NAME}}/advanced-usage/proxy-management/" class="list-group-item">Proxy Management</a>
|
||||
<a href="/{{NAME}}/advanced-usage/repository-management/" class="list-group-item">Repository Management</a>
|
||||
|
||||
<a href="#" class="list-group-item disabled">Community Contributions</a>
|
||||
|
||||
|
||||
@@ -9,6 +9,9 @@
|
||||
"process-management": "deployment/process-management/",
|
||||
"remote-commands": "deployment/remote-commands/",
|
||||
|
||||
"deployment/buildpacks": "deployment/methods/buildpacks/",
|
||||
"deployment/dockerfiles": "deployment/methods/dockerfiles/",
|
||||
"deployment/images": "deployment/methods/images/",
|
||||
"configuration-management": "configuration/environment-variables/",
|
||||
"deployment/ssl-configuration": "configuration/ssl/",
|
||||
"dns": "configuration/dns/",
|
||||
|
||||
@@ -7,7 +7,6 @@ case "$1" in
|
||||
help_content_func () {
|
||||
declare desc="return tar plugin help content"
|
||||
cat<<help_content
|
||||
tar, An alternative to using git. Apps are loaded via tarballs instead
|
||||
tar:in <app>, Reads an tarball containing the app from stdin
|
||||
tar:from <app> <url>, Loads an app tarball from url
|
||||
help_content
|
||||
|
||||
Reference in New Issue
Block a user