info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Switching to Puma **(FREE SELF)**
# Puma **(FREE SELF)**
As of GitLab 12.9, [Puma](https://github.com/puma/puma) has replaced [Unicorn](https://yhbt.net/unicorn/)
as the default web server. From GitLab 14.0, the following run Puma:
NOTE:
Starting with GitLab 13.0, Puma
is the default web server and Unicorn has been
disabled by default. In GitLab 14.0, Unicorn was removed from the Linux package
and only Puma is available.
- All-in-one package-based installations.
- Helm chart-based installations.
Puma is a simple, fast, multi-threaded, and highly concurrent HTTP 1.1 server for
Ruby applications. It's the default GitLab web server since GitLab 13.0
and has replaced Unicorn. From GitLab 14.0, Unicorn is no longer supported.
## Why switch to Puma?
## Configure Puma
Puma has a multi-thread architecture which uses less memory than a multi-process
application server like Unicorn. On GitLab.com, we saw a 40% reduction in memory
consumption.
To configure Puma:
Most Rails applications requests normally include a proportion of I/O wait time.
During I/O wait time MRI Ruby will release the GVL (Global VM Lock) to other threads.
Multi-threaded Puma can therefore still serve more requests than a single process.
1. Determine suitable Puma worker and thread [settings](../../install/requirements.md#puma-settings).
1. If you're swithcing from Unicorn, [convert any custom settings to Puma](#convert-unicorn-settings-to-puma).
1. For multi-node deployments, configure the load balancer to use the
By default, the [Puma Worker Killer](https://github.com/schneems/puma_worker_killer) will restart
a worker if it exceeds a [memory limit](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/cluster/puma_worker_killer_initializer.rb). Additionally, rolling restarts of
Puma workers are performed every 12 hours.
To change the memory limit setting:
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
puma['per_worker_max_memory_mb']=1024
```
1. Reconfigure GitLab for the changes to take effect:
```shell
sudo gitlab-ctl reconfigure
```
## Worker timeout
A [timeout of 60 seconds](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/rack_timeout.rb)
is used when Puma is enabled.
NOTE:
Unlike Unicorn, the `puma['worker_timeout']` setting does not set the maximum request duration.
## Configuring Puma to replace Unicorn
To change the worker timeout:
Beginning with GitLab 13.0, Puma is the default application server. We removed support for
Unicorn in GitLab 14.0.
1. Edit `/etc/gitlab/gitlab.rb`:
When switching to Puma, Unicorn server configuration
will _not_ carry over automatically, due to differences between the two application servers. For Omnibus-based
deployments, see [Configuring Puma Settings](https://docs.gitlab.com/omnibus/settings/puma.html#configuring-puma-settings).
For Helm based deployments, see the [`webservice` chart documentation](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html).
```ruby
gitlab_rails['env']={
'GITLAB_RAILS_RACK_TIMEOUT'=>600
}
```
Additionally we strongly recommend that multi-node deployments [configure their load balancers to use the readiness check](../load_balancer.md#readiness-check) due to a difference between Unicorn and Puma in how they handle connections during a restart of the service.
1. Reconfigure GitLab for the changes to take effect:
```shell
sudo gitlab-ctl reconfigure
```
## Running in memory-constrained environments
In a memory-constrained environment with less than 4GB of RAM available, consider disabling Puma [Clustered mode](https://github.com/puma/puma#clustered-mode).
Configuring Puma by setting the amount of `workers` to `0` could reduce memory usage by hundreds of MB.
For details on Puma worker and thread settings, see the [Puma requirements](../../install/requirements.md#puma-settings).
Unlike in a Clustered mode, which is set up by default, only a single Puma process would serve the application.
The downside of running Puma with such configuration is the reduced throughput, and it could be considered as a fair tradeoff in a memory-constraint environment.
When running Puma in Single mode, some features are not supported:
- Phased restart will not work: [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300665)
@@ -170,11 +170,13 @@ of GitLab Support or other GitLab engineers.
## Puma settings
The recommended settings for Puma are determined by the infrastructure on which it's running.
Omnibus GitLab defaults to the recommended Puma settings. Regardless of installation method, you can
tune the Puma settings.
The GitLab Linux package defaults to the recommended Puma settings. Regardless of installation method, you can
tune the Puma settings:
If you're using Omnibus GitLab, see [Puma settings](https://docs.gitlab.com/omnibus/settings/puma.html)
for instructions on changing the Puma settings. If you're using the GitLab Helm chart, see the [`webservice` chart](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html).
- If you're using the GitLab Linux package, see [Puma settings](../administration/operations/puma.md)
