To keep a YouTube stream running with Docker Compose, define the encoder as a service, set restart: unless-stopped, and start it with docker compose up -d. The command runs the service in the background; the restart policy asks Docker to restart the container after it exits and when Docker restarts, unless you deliberately stopped it.
Those settings improve recovery at the container layer, not uninterrupted broadcasting. They cannot restore power or internet, repair an encoder that is still running but stuck, correct a rejected stream key, or make YouTube accept an unhealthy feed. Treat the policy as one part of an operating plan, not a guarantee that viewers will always see a live picture.
Understand the encoder container architecture
A container runs a process defined by its image and configuration. For a prerecorded 24/7 channel, that process might read a video file, encode or package the media as required, and send it to YouTube’s ingest endpoint. Docker manages the container lifecycle; the encoder handles the media and connection. Compose lets you describe that container and its settings in a service definition.
This distinction matters when something goes wrong. If the encoder process exits, Docker can act on the configured restart policy. If the process remains alive while its output freezes, Docker may see a running container and do nothing. If the container starts again but cannot reach YouTube, the policy does not make the network connection succeed. The same separation applies when YouTube receives a connection but reports a stream-health problem.
YouTube’s encoder setup guidance describes using an encoder to send a live feed. The stream URL and key belong in the encoder’s configuration, while Docker’s restart behaviour belongs in the Compose service. Do not assume that setting one configures the other.
For an always-on channel, decide what the container is meant to do after a restart: resume the same media, reconnect to the ingest endpoint, and report useful errors. Those behaviours depend on the selected encoder and its documented configuration. The Compose example below is deliberately structural; it does not specify an image, command, codec, or secret-injection method that has not been validated for your encoder.
If you are deciding where the encoder should run, consider the practical limits of the host as well as the container configuration. A local computer may be familiar but depends on household power and broadband. A dedicated host may reduce some local interruptions but still has its own maintenance, network, and account dependencies. The trade-offs for a hosted machine are discussed in choosing an Indian VPS for a continuous prerecorded stream.
Define the Compose service
A minimal Compose file names the service, selects an encoder image, and sets its restart policy. The image name below is a placeholder, not a recommendation. Add the actual input, output, and credential configuration only as specified by the encoder’s documentation.
services:
stream:
image: your-encoder-image
restart: unless-stopped
# Configure input, output URL, and stream key
# using the encoder image's documented interface.
Save the file as compose.yaml in the directory from which you intend to manage the service. Compose uses the file to describe the desired service configuration; Docker creates and manages the corresponding container. If your image needs mounted media, persistent files, or environment settings, configure them according to the image’s documentation and your security requirements. This example does not establish a safe or complete deployment by itself.
Keep the stream key out of a public repository, screenshots, and copied logs. YouTube describes the key as functioning like a password for the stream and says it is entered into the encoder. Use an appropriate secret-management or environment-injection method for your deployment, and restrict access to the file or system that holds it. The official YouTube stream settings guidance explains the stream URL and key; consult it in your own account rather than relying on an old copied value.
Compose configuration can also involve multiple services, but avoid applying a restart policy indiscriminately. A long-running encoder is different from a one-off maintenance task that is supposed to exit. Set lifecycle behaviour for each service according to its purpose, and do not assume a dependent service’s existence proves that the encoder has a usable input or connection.
Configure restart: unless-stopped
The restart field tells Docker how to respond when a service container terminates. With unless-stopped, Docker attempts to restart it regardless of exit code, except when the operator has deliberately stopped it or it has been removed. The Compose service reference documents the available policies and their service-level meaning.
For an unattended encoder, this is often a useful default: a process crash can trigger a restart, while an intentional stop remains intentional. For example, if you stop the service to replace a video file or investigate a configuration problem, you generally do not want Docker to bring it straight back against your decision. Check Docker’s current automatic container restart documentation for the precise behaviour of the Engine version you run.
| Policy | What triggers a restart | Operational trade-off |
|---|---|---|
no |
Nothing automatically | The default; a stopped encoder needs operator action. |
on-failure |
An error exit; an optional retry limit can be specified | A clean exit does not meet the failure condition. A retry cap can prevent endless retries. |
always |
The container is restarted unless removed | Manual-stop behaviour across a daemon restart differs from unless-stopped; verify that this matches your operating practice. |
unless-stopped |
The container exits, except after an intentional stop | Suitable when crash recovery is wanted but a deliberate stop should persist. |
No policy is a health check. Docker’s documentation notes that a restart policy only takes effect after the container has started successfully; in this context, that means it has been up for at least 10 seconds while Docker monitors it. That startup condition does not mean the stream has been accepted by YouTube or that the media is progressing correctly.
A restart loop can also conceal the underlying fault. If an encoder repeatedly exits because a file path is wrong or credentials are invalid, Docker may keep trying to start it without fixing the cause. Review logs and correct the configuration rather than treating repeated restarts as recovery. Avoid using a separate host-level process manager to control the same containers alongside Docker’s restart policy, since competing supervisors can create confusing behaviour.
Start with docker compose up -d
From the directory containing the Compose file, run:
docker compose up -d
The -d option means detached mode. Compose starts the defined services and returns control of the terminal while the containers continue running in the background. This answers the narrow question, “Will it keep running when I close this terminal?” It does not configure recovery after a container exits; that is the separate role of restart: unless-stopped. Docker explains this behaviour in its Compose up command reference.
Check that the service was created and is running:
docker compose ps
Then inspect its output when needed:
docker compose logs -f stream
The first command shows container state. The second follows logs for the service named stream in the example. A status such as “running” is useful, but it only describes Docker’s view of the process and container. It does not verify that frames are reaching the correct YouTube channel or that playback is healthy for viewers.
If you edit the Compose file, do not assume that docker compose restart applies the changed configuration. Docker documents that the restart command restarts existing containers; configuration changes require the appropriate Compose reconciliation workflow, such as bringing the service up again with the updated file. Read the command documentation before changing a live service, and retain a known-good copy of the configuration so you can identify what changed.
Detached mode also means you should make a plan for routine observation. Decide who will notice a stopped service, a repeated exit, or a YouTube warning, and how they will access the host and logs. For a channel that cannot be watched from the same machine that runs the encoder, use a separate check of the live feed rather than treating a closed terminal as proof of continued broadcasting.
Verify process and container recovery
First confirm ordinary startup: the service appears in docker compose ps, and logs show that the encoder has read its configured input and attempted to connect. Then confirm the intended restart behaviour in a controlled maintenance window, using a safe test rather than disrupting a public broadcast without warning. You can observe the container state and logs around a test exit, but choose a test method compatible with the encoder and Docker configuration.
A restart is useful only if the encoder can start cleanly again. Check whether the media file is still accessible, whether required mounts persist, whether the key is supplied on each start, and whether the encoder attempts to reconnect. If a container starts and exits in a loop, preserve the relevant logs, identify the first failure message, and correct its cause. Do not suppress useful error output just to make the logs look quiet.
Graceful shutdown behaviour matters too. Compose sends a termination signal and waits before forcefully stopping a container; the documented default timeout is 10 seconds. An encoder that handles its termination signal can close its output cleanly, while a process that ignores it may be killed after the wait. Use the selected image’s guidance on signal handling and command form, particularly if you customise its entry point.
A container that remains running is not necessarily healthy. A frozen input, stalled encode, or disconnected output may leave the process alive. Whether the encoder can detect and reconnect from those conditions depends on its own capabilities and settings; Docker’s restart policy alone does not monitor them. Consult the encoder’s authoritative documentation for its reconnect and health-reporting behaviour.
For a prerecorded service, retain a note of the file version and configuration used for each change. If a replacement file introduces a decode error, being able to distinguish that change from a Docker restart or a credential edit shortens diagnosis. Keep operational notes private if they contain channel identifiers, connection details, or other information you would not want exposed.
Check YouTube stream health separately
Once Docker reports a running container, check the live control room and the actual viewer-facing playback. YouTube’s encoder workflow needs the correct stream URL and key, and YouTube must receive a usable feed. A green or running state in Docker cannot establish either fact. Look for YouTube’s ingest and stream-health indicators, and check playback from a separate device or connection where practical.
If YouTube reports a warning, identify whether it concerns the received feed rather than container status. A live feed can be connected but have a quality or compatibility problem. The troubleshooting steps in YouTube stream health warnings after switching from RTMP to RTMPS are relevant when a transport change is part of the problem. Check YouTube’s current guidance and the encoder’s current output settings before altering a working broadcast.
Account readiness is another separate condition. YouTube says first-time live streaming may take up to 24 hours to become available after enabling the feature. This is a reason to test the channel in advance, not a Docker wait period or a promise that a particular account will be ready at a particular time. Check the current YouTube live-stream enablement help page for account-specific requirements.
Auto-start, auto-stop, and latency are YouTube-side choices, not Compose restart settings. Lower latency can increase playback buffering, so it may not be useful for a non-interactive devotional, music, or ambience loop. Choose settings according to the stream and audience, then verify their effect in YouTube’s own interface rather than copying settings from a different channel.
For ongoing checks, combine three views: container state, encoder logs, and YouTube’s received-stream status. Each answers a different question. If viewers report a blank or frozen picture while the container stays up, investigate the encoder and ingest path instead of repeatedly restarting a container that Docker already considers running.
Account for host, network, and credential failures
A container restart policy operates only while Docker and its host can act. A power cut, host crash, disk failure, Docker daemon problem, or machine maintenance can interrupt the stream. When the host returns, the policy may help bring the service back, but it cannot make the outage disappear or guarantee that the broadcast resumes without a gap. Consider how the machine itself will recover, who can inspect it, and whether you need a separate alert for loss of the live feed.
The network is another boundary. If the broadband connection or route to YouTube fails, a running encoder may lose its output connection. The restart policy reacts to container termination, not every network disruption. Reconnection may be handled by the encoder, but you must verify that behaviour for the chosen image. If the feed degrades when upload capacity falls, steps for streaming when upload speed drops can help frame the network side of diagnosis.
Credentials and platform acceptance have their own failure modes. A revoked or mistyped key, an incorrect stream URL, a changed account setting, or a YouTube-side interruption is not corrected by restarting Docker. Protect the key, confirm it belongs to the intended stream, and check the live control room after changes. Do not put the key in public Compose files or paste it into a public support thread.
A restart policy is also not a substitute for a human operating procedure. Write down how to stop the service deliberately, where its configuration and logs live, how to roll back a bad edit, and how to tell a container outage from a YouTube ingest warning. For a non-technical channel owner, a short tested checklist is more useful than a complex policy nobody remembers during an overnight interruption.
If maintaining a computer and its Docker installation is the pain point, a managed route may remove that particular burden. StreamNeo takes an uploaded video and runs it as a YouTube live stream without leaving your own computer on; it does not remove the need to prepare the file, set up the channel, or check YouTube-side status. It is YouTube-only, so it is not a fit if you need to send the same feed to another platform.
Before committing, compare the operating options on the pricing page. When the file and channel are ready, start free — 24-hour trial, no card.
FAQ
Will docker compose up -d keep my stream running after I close the terminal?
It starts the defined services in detached mode, so the containers continue running after Compose returns control of the terminal. Recovery after a container exits is a separate setting, such as restart: unless-stopped. Neither behaviour guarantees that YouTube is receiving a healthy feed.
Does restart: unless-stopped make YouTube Live uninterrupted?
No. It asks Docker to restart the container after it exits, while respecting an intentional stop. It cannot fix power, host, network, credential, encoder-health, or YouTube-side failures, and a restart can still leave a gap in the broadcast.
What is the difference between always and unless-stopped?
Both are restart policies for a container that terminates, but they differ in how an intentional manual stop is treated when Docker restarts. Docker documents the exact behaviour; choose based on whether a deliberate stop should remain in effect after a daemon restart, and verify against your Engine version.
How can I tell whether the broadcast is healthy?
Use docker compose ps and logs to inspect the container and encoder, then check YouTube’s live control room and viewer-facing playback separately. A running container is not proof that YouTube has accepted a usable feed. If the views disagree, investigate the encoder, network, and ingest status before assuming the restart policy has solved the problem.