/
index.html
139 lines (96 loc) · 8.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
title: IronWorker Documentation
layout: default
section: worker
---
<p class="subtitle">Offload your tasks to the parallel-processing power of the elastic cloud. Write your code, then queue tasks against it—no servers to manage, no scaling to worry about.</p>
<div class="flow-steps">
<div class="step">
<a class="number" href="#write">1</a>
<a class="title" href="#write">Write Your Worker</a>
</div>
<div class="step">
<a class="number" href="#upload">2</a>
<a class="title" href="#upload">Create and Upload Your Code Package</a>
</div>
<div class="step">
<a class="number" href="#tasks">3</a>
<a class="title" href="#queue">Queue/Schedule Your Task</a>
</div>
<div class="step last">
<a class="number" href="#inspect">4</a>
<a class="title" href="#inspect">Inspect Your Worker</a>
</div>
</div>
<h2 id="write">1. Write Your Worker</h2>
<p>IronWorker's <a href="/worker/reference/environment">environment</a> is just a Linux sandbox that your task is executed in. Anything you write that runs on your machine, if packaged correctly, should be able to be run in IronWorker. For example workers, check out the <a href="https://github.com/iron-io/iron_worker_examples">examples repository</a> or the page for <a href="/worker/languages">your favorite language</a>.</p>
<h2 id="upload">2. Create and Upload Your Code Package</h2>
<p>You need to package all your code <strong>and its dependencies</strong> together and upload it to IronWorker before it can be run—your code is run <em>entirely</em> on IronWorker's servers, so it's important that you package <strong>all</strong> the dependencies of your code with it. There are several parts to this step, but you only need to do this when you want to update your worker's code, so you shouldn't have to do it very often.</p>
<div class="alert">
<p><strong>Note:</strong> You only need to upload your code package <em>when your code changes</em>. Queuing tasks <em>does not</em> require you to upload the code package again.</p>
</div>
<p>The suggested way to do this is through a <span class="fixed-width">.worker</span> (pronounced "dotworker") file. There's extensive <a href="/worker/reference/dotworker">documentation</a> for <span class="fixed-width">.worker</span> files, but the snippet below should be enough to get you started. Just save it as "<span class="fixed-width">firstworker.worker</span>" in the same directory as your code.</p>
<figcaption><span>firstworker.worker </span></figcaption>
{% highlight ruby %}
runtime "ruby" # The runtime the code should be run under: ruby, python, php, or sh
exec "path/to/file.rb" # The file to execute when a task is queued. Your worker's entry point
file "config.json" # The path to a file to upload as a dependency of the worker; just leave this out if you don't have any dependencies.
{% endhighlight %}
<div class="alert">
<p><strong>Note:</strong> You should never have a file named <em>just</em> ".worker". Always use a unique, recognisable name—it's what your code package will be named. "helloworld.worker" will create a code package named "helloworld", "turnintoaunicorn.worker" will create a code package named "turnintoaunicorn", etc.</p>
</div>
<p>Once you've defined your worker and its dependencies with a <span class="fixed-width">.worker</span> file, you can upload it using the <a href="/worker/reference/cli">command line tool</a> for IronWorker. <strong>Note:</strong> You'll need to have Ruby 1.9+ installed to use the IronWorker CLI. After that, just run "<span class="fixed-width">gem install iron_worker_ng</span>" to get the tool.</p>
<p>To interact with the IronWorker API, you'll need your project's ID and an auth token from the <a href="https://hud.iron.io">HUD</a>. Once you retrieve them, you need to <a href="/worker/reference/configuration">configure the CLI to use them</a>. Create an <span class="fixed-width">iron.json</span> file in the same folder as your <span class="fixed-width">firstworker.worker</span> file that looks like this:</p>
<figcaption><span>iron.json </span></figcaption>
{% highlight js %}
{
"project_id": "INSERT YOUR PROJECT ID HERE",
"token": "INSERT YOUR AUTH TOKEN HERE"
}
{% endhighlight %}
<p>Once that's done, you can just run the following command:</p>
<figcaption><span>Command Line </span></figcaption>
<div class="cli">
{% highlight bash %}
$ iron_worker upload firstworker
{% endhighlight %}
</div>
<p>That will upload the code package to IronWorker and name it "firstworker"—you'll use the name to queue tasks to the package. That's it, your code is ready to be run!</p>
<h2 id="tasks">3. Queue/Schedule Your Task</h2>
<p>Now that you've uploaded your worker, you can just queue tasks against it to run them, in parallel, in the cloud. You can queue a task directly from <a href="/worker/languages">your favorite language</a> or from the command line:</p>
<figcaption><span>Command Line </span></figcaption>
{% highlight bash %}
$ iron_worker queue firstworker
{% endhighlight %}
<p>You can also specify a payload, which is a string that will be supplied to your worker while it runs the task, letting you pass in information. Almost all payloads are JSON strings:</p>
<figcaption><span>Command Line </span></figcaption>
{% highlight bash %}
$ iron_worker queue firstworker -p '{"key1": "val1", "obj1": {"key2": "val2"}, "arr1": ["item1", "item2"]}'
{% endhighlight %}
<p>Most clients—including the CLI—will automatically handle parsing the payload in your worker, so you can just access the variable or function they give you in your worker's code. We have <a href="/worker/reference/payload">more information</a> on payloads, if you're curious.</p>
<div class="alert">
<p><strong>Protip:</strong> we also offer a <a href="/worker/webhooks">webhook endpoint</a>—it's great for automating tasks. <a href="http://blog.iron.io/2012/04/one-webhook-to-rule-them-all-one-url.html">Check out our blog post</a> for more information on this.</p>
</div>
<p>Sometimes you want tasks that repeat periodically, or that will be queued (queued, not executed) at a specific time or even date. IronWorker supports <a href="/worker/scheduling">scheduled tasks</a> for this purpose. They're just like regular tasks (payloads, executed in the cloud, in parallel), but they're queued on your schedule.</p>
<p>Again, you can schedule a task from your <a href="/worker/languages">favorite language</a> or from the command line:</p>
<figcaption><span>Command Line </span></figcaption>
{% highlight bash %}
$ iron_worker schedule firstworker --start-at "2012-07-19T23:51:00-04:00"
{% endhighlight %}
<p>If you want to just start a task after a short delay, you can do that too. Just specify <span class="fixed-width">--delay</span> followed by the number of seconds the task should be delayed.</p>
<figcaption><span>Command Line </span></figcaption>
{% highlight bash %}
$ iron_worker schedule firstworker --delay 120
{% endhighlight %}
</p>If you want to have a task repeat, you can just specify the <span class="fixed-width">--run-every</span> option, followed by the number of seconds between each run:</p>
<figcaption><span>Command Line </span></figcaption>
{% highlight bash %}
$ iron_worker schedule firstworker --run-every 60
{% endhighlight %}
<p>There are a lot of options to configure scheduling tasks; check our <a href="/worker/scheduling">more detailed guide</a> to see more of the options.</p>
<h2 id="inspect">4. Inspect Your Worker (Logging)</h2>
<p>In a perfect world, your workers would just work. Sometimes though, workers have bugs in them or an API is down or something goes wrong. In these situations, it's helpful to have some debugging tools.</p>
<p>To aid in debugging, everything that is printed to STDOUT (everything from <span class="fixed-width">puts</span> or <span class="fixed-width">print</span> or <span class="fixed-width">echo</span> or your language's equivalent) in a worker is logged in the <a href="https://hud.iron.io">HUD</a>.</p>
<p>Also, in case you think your package wasn't built correctly or forget which version of your worker is running, the HUD offers downloads for every revision of every code package you upload.</p>
<h2>Next Steps</h2>
<p>You should be well-grounded in the IronWorker paradigm now—now you need to build something cool! Check out our <a href="/worker/languages">language documentation</a> or <a href="/worker/reference">reference material</a> to explore the boundaries of IronWorker's system. If you're looking for ideas about what you can accomplish with IronWorker, you may want to check out our <a href="/solutions">solutions</a>.</p>