No examples of use in documentation for link '--alias' option

[phlummox]

Description of problem

Running dokku postgres:help alias gives output including the following:

-a|--alias "BLUE_DATABASE": an alternative alias to use for linking to an app via environment variable

It's not clear from this what the effect of the --alias option is – "linking to an app via environment variable" is very vague. Does it somehow make the environment variable BLUE_DATABASE available in the app container? And if so, what value is the variable set to – the same as DATABASE_URL? Something else?

How reproducible

By running dokku postgres:help alias.

Expected Results

It would be helpful if the documentation or the README could include a full example of how this option is supposed to be used.

Environment Information

n/a

dokku report APP_NAME output

output of dokku report

-----> uname: Linux waldorf 5.4.0-137-generic dokku/dokku-postgres#154-Ubuntu SMP Thu Jan 5 17:03:22 UTC 2023 x86_64 x86_64 x86_64 GNU/Linux
-----> memory: 
                     total        used        free      shared  buff/cache   available
       Mem:            976         382         103          14         490         417
       Swap:          4095         251        3844
-----> docker version: 
       Client: Docker Engine - Community
        Version:           24.0.2
        API version:       1.43
        Go version:        go1.20.4
        Git commit:        cb74dfc
        Built:             Thu May 25 21:52:22 2023
        OS/Arch:           linux/amd64
        Context:           default
       
       Server: Docker Engine - Community
        Engine:
         Version:          24.0.2
         API version:      1.43 (minimum version 1.12)
         Go version:       go1.20.4
         Git commit:       659604f
         Built:            Thu May 25 21:52:22 2023
         OS/Arch:          linux/amd64
         Experimental:     false
        containerd:
         Version:          1.6.21
         GitCommit:        3dce8eb055cbb6872793272b4f20ed16117344f8
        runc:
         Version:          1.1.7
         GitCommit:        v1.1.7-0-g860f061
        docker-init:
         Version:          0.19.0
         GitCommit:        de40ad0
-----> docker daemon info: 
       Client: Docker Engine - Community
        Version:    24.0.2
        Context:    default
        Debug Mode: true
        Plugins:
         buildx: Docker Buildx (Docker Inc.)
           Version:  v0.10.5
           Path:     /usr/libexec/docker/cli-plugins/docker-buildx
         compose: Docker Compose (Docker Inc.)
           Version:  v2.18.1
           Path:     /usr/libexec/docker/cli-plugins/docker-compose
       
       Server:
        Containers: 5
         Running: 5
         Paused: 0
         Stopped: 0
        Images: 14
        Server Version: 24.0.2
        Storage Driver: overlay2
         Backing Filesystem: extfs
         Supports d_type: true
         Using metacopy: false
         Native Overlay Diff: true
         userxattr: false
        Logging Driver: json-file
        Cgroup Driver: cgroupfs
        Cgroup Version: 1
        Plugins:
         Volume: local
         Network: bridge host ipvlan macvlan null overlay
         Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
        Swarm: inactive
        Runtimes: runc io.containerd.runc.v2
        Default Runtime: runc
        Init Binary: docker-init
        containerd version: 3dce8eb055cbb6872793272b4f20ed16117344f8
        runc version: v1.1.7-0-g860f061
        init version: de40ad0
        Security Options:
         apparmor
         seccomp
          Profile: builtin
        Kernel Version: 5.4.0-137-generic
        Operating System: Ubuntu 20.04.6 LTS
        OSType: linux
        Architecture: x86_64
        CPUs: 1
        Total Memory: 976.9MiB
        Name: waldorf
        ID: PEEB:CHZO:EMP7:XJR5:2ZB7:QM5F:TPDW:PHRP:MO73:X7YR:V5PN:LJDA
        Docker Root Dir: /var/lib/docker
        Debug Mode: false
        Experimental: false
        Insecure Registries:
         127.0.0.0/8
        Live Restore Enabled: false
       
-----> git version: git version 2.25.1
-----> sigil version: 0.9.0build+bc921b7
-----> herokuish version: 
       herokuish: v0.6.0
       buildpacks:
         heroku-buildpack-multi     v1.2.0
         heroku-buildpack-ruby      v254
         heroku-buildpack-nodejs    v213
         heroku-buildpack-clojure   v90
         heroku-buildpack-python    v232
         heroku-buildpack-java      v72
         heroku-buildpack-gradle    v39
         heroku-buildpack-scala     v96
         heroku-buildpack-play      v26
         heroku-buildpack-php       v234
         heroku-buildpack-go        v174
         heroku-buildpack-nginx     v23
         buildpack-null             v3
-----> dokku version: dokku version 0.29.4
-----> plugn version: plugn: 0.12.0build+3a27594
-----> dokku plugins: 
         00_dokku-standard    0.29.4 enabled    dokku core standard plugin
         20_events            0.29.4 enabled    dokku core events logging plugin
         app-json             0.29.4 enabled    dokku core app-json plugin
         apps                 0.29.4 enabled    dokku core apps plugin
         builder              0.29.4 enabled    dokku core builder plugin
         builder-dockerfile   0.29.4 enabled    dokku core builder-dockerfile plugin
         builder-herokuish    0.29.4 enabled    dokku core builder-herokuish plugin
         builder-lambda       0.29.4 enabled    dokku core builder-lambda plugin
         builder-null         0.29.4 enabled    dokku core builder-null plugin
         builder-pack         0.29.4 enabled    dokku core builder-pack plugin
         buildpacks           0.29.4 enabled    dokku core buildpacks plugin
         caddy-vhosts         0.29.4 enabled    dokku core caddy-vhosts plugin
         certs                0.29.4 enabled    dokku core certificate management plugin
         checks               0.29.4 enabled    dokku core checks plugin
         common               0.29.4 enabled    dokku core common plugin
         config               0.29.4 enabled    dokku core config plugin
         cron                 0.29.4 enabled    dokku core cron plugin
         docker-options       0.29.4 enabled    dokku core docker-options plugin
         domains              0.29.4 enabled    dokku core domains plugin
         enter                0.29.4 enabled    dokku core enter plugin
         git                  0.29.4 enabled    dokku core git plugin
         letsencrypt          0.12.1 enabled    Automated installation of let's encrypt TLS certificates
         logs                 0.29.4 enabled    dokku core logs plugin
         network              0.29.4 enabled    dokku core network plugin
         nginx-vhosts         0.29.4 enabled    dokku core nginx-vhosts plugin
         plugin               0.29.4 enabled    dokku core plugin plugin
         postgres             1.34.0 enabled    dokku postgres service plugin
         proxy                0.29.4 enabled    dokku core proxy plugin
         ps                   0.29.4 enabled    dokku core ps plugin
         registry             0.29.4 enabled    dokku core registry plugin
         repo                 0.29.4 enabled    dokku core repo plugin
         resource             0.29.4 enabled    dokku core resource plugin
         run                  0.29.4 enabled    dokku core run plugin
         scheduler            0.29.4 enabled    dokku core scheduler plugin
         scheduler-docker-local 0.29.4 enabled    dokku core scheduler-docker-local plugin
         scheduler-null       0.29.4 enabled    dokku core scheduler-null plugin
         shell                0.29.4 enabled    dokku core shell plugin
         ssh-keys             0.29.4 enabled    dokku core ssh-keys plugin
         storage              0.29.4 enabled    dokku core storage plugin
         trace                0.29.4 enabled    dokku core trace plugin
         traefik-vhosts       0.29.4 enabled    dokku core traefik-vhosts plugin
         vouch-auth           0.1.0 enabled    Authentication using Vouch proxy
=====> pyblog app-json information
       App json computed selected:    app.json
       App json global selected:      app.json
       App json selected:             
=====> pyblog app information
       App created at:                1675489846
       App deploy source:             pyblog
       App deploy source metadata:    pyblog
       App dir:                       /home/dokku/pyblog
       App locked:                    false
=====> pyblog builder information
       Builder build dir:             
       Builder computed build dir:    
       Builder computed selected:     
       Builder global build dir:      
       Builder global selected:       
       Builder selected:              
=====> pyblog builder-dockerfile information
       Builder dockerfile computed dockerfile path: Dockerfile               
       Builder dockerfile global dockerfile path: Dockerfile               
       Builder dockerfile dockerfile path:                          
=====> pyblog builder-lambda information
       Builder lambda computed lambdayml path: lambda.yml               
       Builder lambda global lambdayml path: lambda.yml               
       Builder lambda lambdayml path:                          
=====> pyblog builder-pack information
       Builder pack computed projecttoml path: project.toml             
       Builder pack global projecttoml path: project.toml             
       Builder pack projecttoml path:                          
=====> pyblog buildpacks information
       Buildpacks computed stack:     gliderlabs/herokuish:latest-20
       Buildpacks global stack:       
       Buildpacks list:               
       Buildpacks stack:              
=====> pyblog ssl information
       Ssl dir:                       /home/dokku/pyblog/tls   
       Ssl enabled:                   true                     
       Ssl hostnames:                 pyblog.waldorf.info
       Ssl expires at:                Feb  5 23:00:43 2024 GMT 
       Ssl issuer:                    C = US, O = Let's Encrypt, CN = R3
       Ssl starts at:                 Nov  7 23:00:44 2023 GMT 
       Ssl subject:                   subject=CN = pyblog.waldorf.info
       Ssl verified:                  self signed              
=====> pyblog checks information
       Checks disabled list:          none                     
       Checks skipped list:           none                     
       Checks computed wait to retire: 60                       
       Checks global wait to retire:  60                       
       Checks wait to retire:                                  
=====> pyblog cron information
       Cron task count:               0
=====> pyblog docker options information
       Docker options build:                                   
       Docker options deploy:         --restart=on-failure:10  
       Docker options run:                                     
=====> pyblog domains information
       Domains app enabled:           true                     
       Domains app vhosts:            pyblog.waldorf.info
       Domains global enabled:        true                     
       Domains global vhosts:         waldorf.info
=====> pyblog git information
       Git deploy branch:             master                   
       Git global deploy branch:      master                   
       Git keep git dir:              false                    
       Git rev env var:               GIT_REV                  
       Git sha:                       4be1026                  
       Git source image:                                       
       Git last updated at:           1672665180               
=====> pyblog logs information
       Logs computed max size:        10m
       Logs global max size:          10m
       Logs global vector sink:       
       Logs max size:                 
       Logs vector sink:              
=====> pyblog network information
       Network attach post create:           
       Network attach post deploy:           
       Network bind all interfaces:          false
       Network computed attach post create:  
       Network computed attach post deploy:  
       Network computed bind all interfaces: false
       Network computed initial network:     
       Network computed tld:                 
       Network global attach post create:    
       Network global attach post deploy:    
       Network global bind all interfaces:   false
       Network global initial network:       
       Network global tld:                   
       Network initial network:              
       Network static web listener:          
       Network tld:                          
       Network web listeners:                172.17.0.3:6000
=====> pyblog nginx information
       Nginx access log format:                                
       Nginx access log path:         /var/log/nginx/pyblog-access.log
       Nginx bind address ipv4:                                
       Nginx bind address ipv6:       ::                       
       Nginx client max body size:                             
       Nginx disable custom config:   false                    
       Nginx error log path:          /var/log/nginx/pyblog-error.log
       Nginx global hsts:             true                     
       Nginx computed hsts:           true                     
       Nginx hsts:                                             
       Nginx hsts include subdomains: true                     
       Nginx hsts max age:            15724800                 
       Nginx hsts preload:            false                    
       Nginx computed nginx conf sigil path: nginx.conf.sigil         
       Nginx global nginx conf sigil path: nginx.conf.sigil         
       Nginx nginx conf sigil path:                            
       Nginx proxy buffer size:       4096                     
       Nginx proxy buffering:         on                       
       Nginx proxy buffers:           8 4096                   
       Nginx proxy busy buffers size: 8192                     
       Nginx proxy read timeout:      60s                      
       Nginx last visited at:         1700179201               
       Nginx x forwarded for value:   $remote_addr             
       Nginx x forwarded port value:  $server_port             
       Nginx x forwarded proto value: $scheme                  
       Nginx x forwarded ssl:                                  
=====> pyblog proxy information
       Proxy enabled:                 true
       Proxy port map:                http:6000:6000 http:80:6000 https:443:6000
       Proxy type:                    nginx
=====> pyblog ps information
       Deployed:                      true
       Processes:                     1
       Ps can scale:                  true
       Ps computed procfile path:     Procfile
       Ps global procfile path:       Procfile
       Ps procfile path:              
       Ps restart policy:             on-failure:10
       Restore:                       false
       Running:                       false
       Status web 1:                  missing (CID: ea71af7dd84)
=====> pyblog registry information
       Registry computed image repo:      dokku/pyblog
       Registry computed push on release: false
       Registry computed server:          
       Registry global push on release:   
       Registry global server:            
       Registry image repo:               
       Registry push on release:          
       Registry server:                   
       Registry tag version:              
=====> pyblog resource information
=====> pyblog scheduler information
       Scheduler computed selected:   docker-local
       Scheduler global selected:     docker-local
       Scheduler selected:            
=====> pyblog scheduler-docker-local information
       Scheduler docker local disable chown:                          
       Scheduler docker local init process: true                     
       Scheduler docker local parallel schedule count:                          
=====> pyblog storage information
       Storage build mounts:                                   
       Storage deploy mounts:                                  
       Storage run mounts:                                     

How (deb/make) and where (AWS, VirtualBox, physical, etc.) was Dokku installed?:

From the https://packagecloud.io/dokku/dokku/ubuntu/ repository, on a DigitalOcean VM.