|
| 1 | +Once your release is built, you can execute a number of helpful commands from the entry script. |
| 2 | + |
| 3 | +If you've built a release for `#!elixir :myapp`, you can run `bin/myapp` to see the full list of commands. |
| 4 | + |
| 5 | +## Release tasks |
| 6 | + |
| 7 | +| Task | Description | |
| 8 | +|:--------------------|:--------------------------------------------------------------------------------| |
| 9 | +| start | Start myapp as a daemon | |
| 10 | +| start_boot <file> | Start myapp as a daemon, but supply a custom .boot file | |
| 11 | +| foreground | Start myapp in the foreground<br>This is similar to running `mix run --no-halt` | |
| 12 | +| console | Start myapp with a console attached<br>This is similar to running `iex -S mix` | |
| 13 | +| console_clean | Start a console with code paths set but no apps loaded/started | |
| 14 | +| console_boot <file> | Start myapp with a console attached, but supply a custom .boot file | |
| 15 | +| stop | Stop the myapp daemon | |
| 16 | +| restart | Restart the myapp daemon without shutting down the VM | |
| 17 | +| reboot | Restart the myapp daemon | |
| 18 | +| upgrade <version> | Upgrade myapp to <version> | |
| 19 | +| downgrade <version> | Downgrade myapp to <version> | |
| 20 | +| attach | Attach the current TTY to myapp's console | |
| 21 | +| remote_console | Remote shell to myapp's console | |
| 22 | +| reload_config | Reload the current system's configuration from disk | |
| 23 | +| pid | Get the pid of the running myapp instance | |
| 24 | +| ping | Checks if myapp is running, pong is returned if successful | |
| 25 | +| pingpeer <peer> | Check if a peer node is running, pong is returned if successful | |
| 26 | +| escript | Execute an escript | |
| 27 | +| rpc | Execute Elixir code on the running node | |
| 28 | +| eval | Execute Elixir code locally | |
| 29 | +| describe | Print useful information about the myapp release | |
| 30 | + |
| 31 | +## Running code in releases |
| 32 | + |
| 33 | +Distillery comes with two very useful tasks for working with your release. |
| 34 | + |
| 35 | +* Both will take some Elixir code and run it for you and show you the result. |
| 36 | +* Both tasks use the exact same syntax, the only difference is the context your code is run in. |
| 37 | + |
| 38 | +### Running code with `rpc` |
| 39 | + |
| 40 | +This task executes code on the running node, and is what you'd want to use to interact with your application when _it's already running_. |
| 41 | + |
| 42 | +!!! example "Using Module.fun/arity" |
| 43 | + ```bash tab="Command" |
| 44 | + $ ./bin/myapp rpc --mfa "Application.loaded_applications/0" |
| 45 | + ``` |
| 46 | + |
| 47 | + ```elixir tab="Output" |
| 48 | + [ |
| 49 | + {:lz_string, |
| 50 | + 'Elixir implementation of pieroxy\'s lz-string compression algorithm.', |
| 51 | + '0.0.7'}, |
| 52 | + {:phoenix_html, |
| 53 | + ...snip |
| 54 | + ``` |
| 55 | + |
| 56 | +??? example "Using Module.fun/arity with arguments" |
| 57 | + ```bash tab="Commands" |
| 58 | + $ ./bin/myapp rpc --mfa "Application.put_env/3" -- myapp token supersecret |
| 59 | + $ ./bin/myapp rpc --mfa "Application.get_env/2" -- myapp token |
| 60 | + ``` |
| 61 | + |
| 62 | + ```bash tab="Output" |
| 63 | + $ ./bin/myapp rpc --mfa "Application.put_env/3" -- myapp token supersecret |
| 64 | + :ok |
| 65 | + $ ./bin/myapp rpc --mfa "Application.get_env/2" -- myapp token |
| 66 | + "supersecret" |
| 67 | + ``` |
| 68 | + |
| 69 | +??? example "Using Module.fun/1 with arguments as a single list" |
| 70 | + Here, the `--argv` option can be used to construct a list before passing your arguments to the function specified. |
| 71 | + |
| 72 | + ```bash tab="Command" |
| 73 | + $ ./bin/myapp rpc --mfa "Enum.join/1" --argv -- foo bar baz |
| 74 | + ``` |
| 75 | + |
| 76 | + ```elixir tab="Output" |
| 77 | + "foobarbaz" |
| 78 | + ``` |
| 79 | + |
| 80 | +??? example "Using an expression, getting application version" |
| 81 | + You can also use an expression, but you'll need to be mindful of shell quoting. |
| 82 | + |
| 83 | + ```bash tab="Command" |
| 84 | + $ ./bin/myapp rpc 'Application.spec(:myapp, :vsn)' |
| 85 | + ``` |
| 86 | + |
| 87 | + ```elixir tab="Output" |
| 88 | + '0.0.1' |
| 89 | + ``` |
| 90 | + |
| 91 | +??? example "Using an expression, broadcasting to a Phoenix channel" |
| 92 | + ```bash |
| 93 | + $ ./bin/myapp rpc 'MyappWeb.Endpoint.broadcast!("channel:lobby", "status", %{current_status: "oopsy"})' |
| 94 | + ``` |
| 95 | + |
| 96 | +### Running code with `eval` |
| 97 | + |
| 98 | +This task executes code locally in a clean instance. Although execution will be within the context of your release, no applications will have been started. This is very useful for things like migrations, where you'll want to start only some applications (e.g. Ecto) manually before doing some work. |
| 99 | + |
| 100 | +!!! example "Using Module.fun/arity" |
| 101 | + Assuming that you've created a `Myapp.ReleaseTasks` module, you can call it into like so: |
| 102 | + ``` |
| 103 | + $ ./bin/myapp eval --mfa 'Myapp.ReleaseTasks.migrate/0' |
| 104 | + ``` |
| 105 | + |
| 106 | +??? example "Using Module.fun/arity with arguments" |
| 107 | + Like with `rpc`, arguments can be specified (but are generally treated as strings). |
| 108 | + |
| 109 | + ```bash |
| 110 | + $ ./bin/myapp eval --mfa 'File.touch/1' -- /tmp/foo |
| 111 | + :ok |
| 112 | + ``` |
| 113 | + |
| 114 | +??? example "Using an expression" |
| 115 | + Like with `rpc`, an expression can be used. |
| 116 | + |
| 117 | + ```bash tab="Command" |
| 118 | + $ ./bin/myapp eval 'Timex.Duration.now |> Timex.format_duration(:humanized)' |
| 119 | + ``` |
| 120 | + |
| 121 | + ```elixir tab="Output" |
| 122 | + "48 years, 10 months, 2 weeks, 2 days, 4 hours, 8 minutes, 52 seconds, 883.16 milliseconds" |
| 123 | + ``` |
0 commit comments