carlos / carloku Public

Download this file

1	# Restarting and sleeping
2
3	Your app's process gets cycled for reasons that have nothing to do with new
4	code. You ask for it, a config change forces it, or the platform puts a quiet
5	app to sleep and starts it again when somebody turns up. This page covers the
6	first and the last.
7
8	```sh
9	carlos restart -app hello
10	```
11
12	The reply says *restart requested*, which is the accurate word for what
13	happened: the console wrote one small object, and every box serving the app
14	notices it within seconds and cycles its own routes. No version moves, no
15	channel is consulted, nothing is pushed at a box.
16
17	What cycling looks like depends on how the instance runs. A long-running one
18	stops and comes straight back. An on-demand one stops within seconds and
19	starts again on the next request that needs it — for a quiet app, that may
20	be a while. An instance that is already asleep is left asleep and
21	starts fresh whenever it next wakes.
22
23	Reach for restart when a process is wedged and you have no change to make. A
24	deploy already cycles the app, and so does a config change — see
25	[Deploying](/docs/deploying/) and [Env and secrets](/docs/config/) — so
26	neither of those needs a restart after it.
27
28	## What hibernation is
29
30	An app nobody has talked to for a while is checkpointed to its bucket and its
31	process stopped. The idle window belongs to the deployment; fifteen minutes
32	is the default. The app's state was living in the bucket the whole time, so
33	there is nothing to lose in the transition — the process was only ever the
34	part that reads it.
35
36	```sh
37	carlos instances list -app hello
38	```
39
40	The health column reads `asleep` for those instances and `running` for the
41	rest. For anything without steady traffic, `asleep` is the ordinary
42	condition, not a fault to clear.
43
44	## What a visitor sees
45
46	A request for a sleeping app is held at the edge while the instance wakes,
47	then handed to it. The visitor waits longer for that page and then gets it;
48	there is no error page and nothing for them to retry. Requests that arrive
49	together during a wake all join the same one instead of each starting their
50	own.
51
52	The exception is a wake that takes an unusual length of time. Past about
53	thirty seconds the request is answered with a 503 and a `Retry-After`, and a
54	wake that fails outright ends the same way. In
55	both cases the reason is one line in the platform stream:
56
57	```sh
58	carlos logs -app hello -stream platform -since 15m
59	```
60
61	## Traffic that doesn't wake anything
62
63	The edge keeps its own cache of responses and checks it before it goes
64	anywhere near the wake path, so a crawler asking for the same public page all
65	afternoon can be answered without your app running at all. What makes a
66	response eligible is your app saying so: a 2xx GET with `Cache-Control:
67	max-age=…` and no `Set-Cookie`. Whatever number you set, the edge caps the
68	entry at five minutes, so this cannot strand a page for long. Setting that
69	header on your public pages is the single most useful thing you can do for an
70	app that hibernates.
71
72	A TLS handshake by itself never wakes anything either — only a request that
73	would reach your app does.
74
75	## Work that still happens
76
77	A timetable set with [carlos
78	schedule](https://carlosframework.com/docs/cli/#carlos-schedule) survives
79	hibernation. Before an instance goes to sleep the platform records when its
80	next job falls due, and wakes it when that time arrives; the job runs, and the
81	usual idle window puts it back. You do not have to keep the app awake to keep
82	its schedule.
83
84	Flags for [carlos restart](https://carlosframework.com/docs/cli/#carlos-restart)
85	and [carlos instances](https://carlosframework.com/docs/cli/#carlos-instances)
86	are in the CLI reference.
87