consul/grecia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update Heroku instructions

Browse Source 
Note that the variable related with the "hostname" is removed
from the Heroku instructions as it is not necessary to configure
the Bucket.
This commit is contained in:
taitus
2024-09-16 16:24:11 +02:00
parent c27a32a5f3
commit c267679aeb
4 changed files with 183 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
docs/en/installation/deploying-on-heroku.md
View File

@@ -5,13 +5,13 @@
This tutorial assumes that you have already managed to clone Consul Democracy on your machine and gotten it to work.
1. First, create a [Heroku](https://www.heroku.com) account if it isn't already done.
2. Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and sign in using
2. Install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and sign in using:
```bash
heroku login
```
3. Go to your Consul Democracy repository and instantiate the process
3. Go to your Consul Democracy repository and instantiate the process:
```bash
cd consuldemocracy
@@ -22,7 +22,7 @@ This tutorial assumes that you have already managed to clone Consul Democracy on
If _your-app-name_ is not already taken, Heroku should now create your app.
4. Create a database using
4. Create a database using:
```bash
heroku addons:create heroku-postgresql
@@ -30,19 +30,7 @@ This tutorial assumes that you have already managed to clone Consul Democracy on
You should now have access to an empty Postgres database whose address was automatically saved as an environment variable named _DATABASE\_URL_. Consul Democracy will automatically connect to it when deployed.
5. **(Not needed)** Add a file name _heroku.yml_ at the root of your project and paste the following in it
```yml
build:
languages:
- ruby
packages:
- imagemagick
run:
web: bundle exec rails server -e ${RAILS_ENV:-production}
```
6. Now, generate a secret key and save it to an ENV variable named SECRET\_KEY\_BASE using
5. Now, generate a secret key and save it to an ENV variable named SECRET\_KEY\_BASE using:
```bash
heroku config:set SECRET_KEY_BASE=$(rails secret)
@@ -70,48 +58,72 @@ This tutorial assumes that you have already managed to clone Consul Democracy on
**Remember not to commit the file if you have any sensitive information in it!**
7. You can now push your app using
6. To ensure Heroku correctly detects and uses the node.js and ruby versions defined in the project, we need to make the following changes:
In package.json, add the node.js version:
```json
"engines": {
"node": "18.20.3"
}
```
and apply:
```bash
heroku buildpacks:add heroku/nodejs
```
In _Gemfile_, add the ruby version and run bundle:
```Gemfile
ruby file: ".ruby-version"
```
and apply:
```bash
heroku buildpacks:set heroku/ruby
```
7. You can now push your app using:
```bash
git push heroku your-branch:master
```
8. It won't work straight away because the database doesn't contain the tables needed. To create them, run
8. It won't work straight away because the database doesn't contain the tables needed. To create them, run:
```bash
heroku run rake db:migrate
heroku run rake db:seed
```
If you want to add the test data in the database, move `gem 'faker', '~> 1.8.7'` outside of `group :development` and run
```bash
heroku config:set DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true
heroku config:set DATABASE_CLEANER_ALLOW_PRODUCTION=true
heroku run rake db:dev_seed
```
9. Your app should now be ready to use. You can open it with
9. Your app should now be ready to use. You can open it with:
```bash
heroku open
```
You also can run the console on heroku using
You also can run the console on Heroku using:
```bash
heroku console --app your-app-name
```
10. Heroku doesn't allow to save images or documents in its servers, so it's necessary to setup a permanent storage space.
10. Heroku doesn't allow saving images or documents in its servers, so it's necessary to setup a permanent storage space.
See [our S3 guide](./using-aws-s3-as-storage.md) for more details about configuring Paperclip with S3.
See [our S3 guide](using-aws-s3-as-storage.md) for more details about configuring ActiveStorage with S3.
### Configure Sendgrid
### Configure Twilio Sendgrid
Add the SendGrid add-on in Heroku. It will create a SendGrid account for you with `ENV["SENDGRID_USERNAME"]` and `ENV["SENDGRID_PASSWORD"]`.
Add the Twilio SendGrid add-on in Heroku. This will create a Twilio SendGrid account for the application with a username and allow you to create a password. This username and password can be stored in the application’s environment variables on Heroku:
Add this to `config/secrets.yml`, under the `production:` section:
```bash
heroku config:set SENDGRID_USERNAME=example-username SENDGRID_PASSWORD=xxxxxxxxx
```
Now add this to `config/secrets.yml`, under the `production:` section:
```yaml
mailer_delivery_method: :smtp
@@ -125,62 +137,4 @@ Add this to `config/secrets.yml`, under the `production:` section:
:enable_starttls_auto: true
```
Important: Turn on one worker dyno so that emails get sent.
## Optional but recommended
### Install rails\_12factor and specify the Ruby version
**The rails\_12factor is only useful if you use a version of Consul Democracy older than 1.0.0. The latter uses Rails 5 which includes the changes.**
As recommended by Heroku, you can add the gem rails\_12factor and specify the version of Ruby you want to use. You can do so by adding
```ruby
gem 'rails_12factor'
ruby 'x.y.z'
```
in the file _Gemfile\_custom_, where `x.y.z` is the version defined in the `.ruby-version` file in the Consul Democracy repository. Don't forget to run
```bash
bundle install
```
to generate _Gemfile.lock_ before committing and pushing to the server.
### Use Puma as a web server
Heroku recommends to use Puma to improve the responsiveness of your app on [a number of levels](http://blog.scoutapp.com/articles/2017/02/10/which-ruby-app-server-is-right-for-you).
If you want to allow more concurrency, uncomment the line:
```ruby
workers ENV.fetch("WEB_CONCURRENCY") { 2 }
```
You can find an explanation for each of these settings in the [Heroku tutorial](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server).
The last part is to change the _web_ task to use Puma by changing it to this in your _heroku.yml_ file:
```yml
web: bundle exec puma -C config/puma.rb
```
### Add configuration variables to tune your app from the dashboard
The free and hobby versions of Heroku are barely enough to run an app like Consul Democracy. To optimise the response time and make sure the app doesn't run out of memory, you can [change the number of workers and threads](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#workers) that Puma uses.
My recommended settings are one worker and three threads. You can set it by running these two commands:
```bash
heroku config:set WEB_CONCURRENCY=1
heroku config:set RAILS_MAX_THREADS=3
```
I also recommend to set the following:
```bash
heroku config:set RAILS_SERVE_STATIC_FILES=enabled
heroku config:set RAILS_ENV=production
```
**Important:** Turn on one worker dyno so that emails get sent.

85
docs/en/installation/using-aws-s3-as-storage.md
View File

@@ -1,87 +1,64 @@
# Using AWS S3 as file storage
While Consul Democracy keeps most of its data in a PostgreSQL database, all the files such as documents or images have to be stored elsewhere.
To take care of them, Consul Democracy uses the [Paperclip gem](https://github.com/thoughtbot/paperclip) (Warning: this gem is now deprecated and Consul Democracy will probably migrate to ActiveStorage in the future. Check that this is not already the case before using this guide).
By default, the attachments are stored on the filesystem. However, with services such as Heroku, there is no persistent storage which means that these files are periodically erased.
This tutorial explains how to configure Paperclip to use [AWS S3](https://aws.amazon.com/fr/s3/). It doesn't recommend S3 or the use of Amazon services and will hopefully be expanded to include configuration for [fog storage](http://fog.io/storage/).
Although Consul Democracy stores most of its data in a PostgreSQL database, in Heroku all files, such as documents or images, must be stored elsewhere, such as AWS S3.
## Adding the gem *aws-sdk-s3*
First, add the following line in your *Gemfile_custom*
Add the following line to your *Gemfile_custom*:
```ruby
gem 'aws-sdk-s3', '~> 1'
gem "aws-sdk-s3", "~> 1"
```
Make sure to have a recent version of paperclip (Consul Democracy is currently using 5.2.1, which doesn't recognize *aws-sdk-s3*). In your Gemfile, the line should be:
```ruby
gem 'paperclip', '~> 6.1.0'
```
Run `bundle install` to apply your changes.
And run `bundle install` to apply your changes.
## Adding your credentials in *secrets.yml*
This guide will assume that you have an Amazon account configured to use S3 and that you created a bucket for your instance of Consul Democracy. It is highly recommended to use a different bucket for each instance (production, preproduction, staging).
This guide assumes you have an Amazon account configured to use S3 and that you have created a bucket for your instance of Consul Democracy. It is strongly recommended to use a different bucket for each instance (production, preproduction, staging).
You will need the following information:
- the **name** of the S3 bucket
- the **region** of the S3 bucket (`eu-central-1` for UE-Francfort for example)
- the **hostname** of the S3 bucket (`s3.eu-central-1.amazonaws.com` for Francfort, for example)
- an **access key id** and a **secret access key** with read/write permission to that bucket
- The **name** of the S3 bucket.
- The **region** of the S3 bucket (`eu-central-1` for UE-Francfort for example).
- An **access_key** and a **secret_key** with read/write permission to that bucket.
**WARNING:** It is recommended to create IAM users that will only have read/write permission to the bucket you want to use for that specific instance of Consul Democracy.
**WARNING:** It is recommended to create IAM users (Identity and Access Management) who only have read/write permissions for the bucket you intend to use for that specific instance of Consul Democracy.
Once you have these pieces of information, you can save them as environment variables of the instance running Consul Democracy. In this tutorial, we save them respectively as *AWS_S3_BUCKET*, *AWS_S3_REGION*, *AWS_S3_HOSTNAME*, *AWS_ACCESS_KEY_ID* and *AWS_SECRET_ACCESS_KEY*.
Once you have these pieces of information, you can save them as environment variables of the instance running Consul Democracy. In this tutorial, we save them respectively as *S3_BUCKET*, *S3_REGION*, *S3_ACCESS_KEY_ID* and *S3_SECRET_ACCESS_KEY*.
Add the following block in your *secrets.yml* file:
```yaml
aws: &aws
aws_s3_region: <%= ENV["AWS_S3_REGION"] %>
aws_access_key_id: <%= ENV["AWS_ACCESS_KEY_ID"] %>
aws_secret_access_key: <%= ENV["AWS_SECRET_ACCESS_KEY"] %>
aws_s3_bucket: <%= ENV["AWS_S3_BUCKET"] %>
aws_s3_host_name: <%= ENV["AWS_S3_HOST_NAME"] %>
```bash
heroku config:set S3_BUCKET=example-bucket-name S3_REGION=eu-west-example S3_ACCESS_KEY_ID=xxxxxxxxx S3_SECRET_ACCESS_KEY=yyyyyyyyyy
```
and `<<: *aws` under the environments which you want to use S3 with, for example:
Now add the following block to your *secrets.yml* file:
```yaml
production:
[...]
<<: *aws
s3:
access_key_id: <%= ENV["S3_ACCESS_KEY_ID"] %>
secret_access_key: <%= ENV["S3_SECRET_ACCESS_KEY"] %>
region: <%= ENV["S3_REGION"] %>
bucket: <%= ENV["S3_BUCKET"] %>
```
## Configuring Paperclip
## Enabling the use of S3 in the application
First, activate Paperclip's URI adapter by creating the file *config/initializers/paperclip.rb* with the following content:
First, add the following line inside the `class Application < Rails::Application` class in the `config/application_custom.rb` file:
```ruby
Paperclip::UriAdapter.register
# Store uploaded files on the local file system (see config/storage.yml for options).
config.active_storage.service = :s3
```
Finally, add the following lines in the environment file of the instance which you want to use S3 with. In production, you should for example edit *config/environments/production.rb*.
Then, uncomment the s3 block that you will find in the *storage.yml* file:
```ruby
# Paperclip settings to store images and documents on S3
config.paperclip_defaults = {
storage: :s3,
preserve_files: true,
s3_host_name: Rails.application.secrets.aws_s3_host_name,
s3_protocol: :https,
s3_credentials: {
bucket: Rails.application.secrets.aws_s3_bucket,
access_key_id: Rails.application.secrets.aws_access_key_id,
secret_access_key: Rails.application.secrets.aws_secret_access_key,
s3_region: Rails.application.secrets.aws_s3_region,
}
}
```yaml
s3:
service: S3
access_key_id: <%= Rails.application.secrets.dig(:s3, :access_key_id) %>
secret_access_key: <%= Rails.application.secrets.dig(:s3, :secret_access_key) %>
region: <%= Rails.application.secrets.dig(:s3, :region) %>
bucket: <%= Rails.application.secrets.dig(:s3, :bucket) %>
```
You will need to restart to apply the changes.
You will need to restart the application to apply the changes.

130
docs/es/installation/deploying-on-heroku.md
View File

@@ -11,7 +11,7 @@ Este tutorial asume que ya has conseguido clonar Consul Democracy en tu máquina
heroku login
```
3. Accede a tu repositorio de Consul Democracy y crea una instancia
3. Accede a tu repositorio de Consul Democracy y crea una instancia:
```bash
cd consuldemocracy
@@ -22,7 +22,7 @@ Este tutorial asume que ya has conseguido clonar Consul Democracy en tu máquina
Si _your-app-name_ no existe aún, Heroku creará tu aplicación.
4. Crea la base de datos con
4. Crea la base de datos con:
```bash
heroku addons:create heroku-postgresql
@@ -30,19 +30,7 @@ Este tutorial asume que ya has conseguido clonar Consul Democracy en tu máquina
Ahora deberías tener acceso a una base de datos Postgres vacía cuya dirección se guardó automáticamente como una variable de entorno llamada _DATABASE\_URL_. Consul Democracy se conectará automáticamente a ella durante la instalación.
5. **(No es necesario)** Crea un archivo con el nombre _heroku.yml_ en la raíz del proyecto y añade el siguiente código
```yml
build:
languages:
- ruby
packages:
- imagemagick
run:
web: bundle exec rails server -e ${RAILS_ENV:-production}
```
6. Ahora, genera una clave secreta y guárdala en la variable de entorno SECRET\_KEY\_BASE de la siguinte manera
5. Ahora, genera una clave secreta y guárdala en la variable de entorno SECRET\_KEY\_BASE de la siguiente manera:
```bash
heroku config:set SECRET_KEY_BASE=$(rails secret)
@@ -70,28 +58,48 @@ Este tutorial asume que ya has conseguido clonar Consul Democracy en tu máquina
**¡Recuerda no añadir el archivo si tienes información sensible en él!**
6. Para que Heroku detecte y utilice correctamente las versiones de node.js y ruby definidas en el proyecto deberemos añadir los siguientes cambios:
En el _package.json_ añadir la versión de node.js:
```json
"engines": {
"node": "18.20.3"
}
```
y aplicar:
```bash
heroku buildpacks:add heroku/nodejs
```
En el _Gemfile_ añadir la versión de ruby y ejecutar bundle:
```Gemfile
ruby file: ".ruby-version"
```
y aplicar:
```bash
heroku buildpacks:set heroku/ruby
```
7. Ahora ya puedes subir tu aplicación utilizando:
```bash
git push heroku your-branch:master
```
8. No funcionará de inmediato porque la base de datos no contiene las tablas necesarias. Para crearlas, ejecuta
8. No funcionará de inmediato porque la base de datos no contiene las tablas necesarias. Para crearlas, ejecuta:
```bash
heroku run rake db:migrate
heroku run rake db:seed
```
Si quieres añadir los datos de prueba en la base de datos, mueve `gem 'faker', '~> 1.8.7'` fuera del `group :development` y ejecuta:
```bash
heroku config:set DATABASE_CLEANER_ALLOW_REMOTE_DATABASE_URL=true
heroku config:set DATABASE_CLEANER_ALLOW_PRODUCTION=true
heroku run rake db:dev_seed
```
9. Ahora tu aplicación debería estar ya opertaiva. Puedes abrirla con
9. Ahora tu aplicación debería estar ya operativa. Puedes abrirla con:
```bash
heroku open
@@ -105,13 +113,17 @@ Este tutorial asume que ya has conseguido clonar Consul Democracy en tu máquina
10. Heroku no permite guardar imágenes o documentos en sus servidores, por lo que es necesario configurar un nuevo espacio de almacenamiento.
Consulta [nuestra guía de S3](./using-aws-s3-as-storage.md) para más detalles sobre la configuración de Paperclip con S3.
Consulta [nuestra guía de S3](using-aws-s3-as-storage.md) para más detalles sobre la configuración de ActiveStorage con S3.
### Configurar Sendgrid
### Configurar Twilio SendGrid
Añade el complemento (add-on) de SendGrid en Heroku. Esto creará una cuenta de SendGrid para la aplicación con `ENV["SENDGRID_USERNAME"]` y `ENV["SENDGRID_PASSWORD"]`.
Añade el complemento (_add-on_) de Twilio SendGrid en Heroku. Esto creará una cuenta en Twilio SendGrid para la aplicación con un nombre de usuario y permitirá crear una contraseña. Este usuario y contraseña lo podemos guardar en las variables de entorno de la aplicación en Heroku:
Añade el siguiente código a `config/secrets.yml`, en la sección `production:`:
```bash
heroku config:set SENDGRID_USERNAME=example-username SENDGRID_PASSWORD=xxxxxxxxx
```
Ahora añade el siguiente código a `config/secrets.yml`, en la sección `production:`:
```yaml
mailer_delivery_method: :smtp
@@ -125,62 +137,4 @@ Añade el siguiente código a `config/secrets.yml`, en la sección `production:`
:enable_starttls_auto: true
```
Importante: Activa un "worker dyno" para que se envíen los correos electrónicos.
### Opcional (pero recomendado)
### Instalar rails\_12factor y especificar la versión de Ruby
**Instalar rails\_12factor sólo es útil si utilizas una versión de Consul Democracy anterior a la 1.0.0. La última versión utiliza Rails 5 que ya incluye los cambios.**
Como nos recomienda Heroku, puedes añadir la gema rails\_12factor y especificar la versión de Ruby a utilizar. Puedes hacerlo añadiendo:
```ruby
gem 'rails_12factor'
ruby 'x.y.z'
```
en el archivo _Gemfile\_custom_, donde `x.y.z` es la versión definida en el fichero `.ruby-version` del repositorio de Consul Democracy. No olvides ejecutar
```bash
bundle install
```
para generar el _Gemfile.lock_ antes de añadir los cambios y subirlos al servidor.
### Utilizar Puma como servidor web
Heroku recomienda utilizar Puma para mejorar el [rendimiento](http://blog.scoutapp.com/articles/2017/02/10/which-ruby-app-server-is-right-for-you) de la aplicación.
Si quieres permitir más concurrencia, descomenta la siguiente linea:
```ruby
workers ENV.fetch("WEB_CONCURRENCY") { 2 }
```
Puedes encontrar una explicación para diferentes configuraciones en el siguiente [tutorial de Heroku](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server).
Por último hay que cambiar la tarea _web_ para usar Puma cambiándola en el archivo _heroku.yml_ con el siguiente código:
```yml
web: bundle exec puma -C config/puma.rb
```
### Añadir variables de configuración desde el panel de control
Las versiones gratuita y hobby de Heroku no son suficientes para ejecutar una aplicación como Consul Democracy. Para optimizar el tiempo de respuesta y asegurarte de que la aplicación no se quede sin memoria, puedes [cambiar el número de "workers" e hilos](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server#workers) que utiliza Puma.
La configuración recomendada es un "worker" y tres hilos. Puedes configurarlo ejecutando estos dos comandos:
```bash
heroku config:set WEB_CONCURRENCY=1
heroku config:set RAILS_MAX_THREADS=3
```
También es recomendable configurar las siguientes variables:
```bash
heroku config:set RAILS_SERVE_STATIC_FILES=enabled
heroku config:set RAILS_ENV=production
```
**Importante:** Activa un "_worker dyno_" para que se envíen los correos electrónicos.

64
docs/es/installation/using-aws-s3-as-storage.md Normal file
View File

@@ -0,0 +1,64 @@
# Usar AWS S3 como almacenamiento de archivos
Aunque Consul Democracy almacena la mayor parte de sus datos en una base de datos PostgreSQL, en Heroku todos los archivos como documentos o imágenes deben almacenarse en otro lugar, como puede ser AWS S3.
## Añadir la gema *aws-sdk-s3*
Añade la siguiente línea en tu *Gemfile_custom*:
```ruby
gem "aws-sdk-s3", "~> 1"
```
Y ejecuta `bundle install` para aplicar los cambios.
## Añadir tus credenciales en *secrets.yml*
Esta guía asume que tienes una cuenta de Amazon configurada para usar S3 y que has creado un _bucket_ para tu instancia de Consul Democracy. Se recomienda encarecidamente usar un _bucket_ diferente para cada instancia (producción, preproducción, staging).
Necesitarás la siguiente información:
- El **nombre** del _bucket_.
- La **región** del _bucket_ (`eu-central-1` para UE-Frankfurt, por ejemplo).
- Una **_access_key_** y un **_secret_key_** con permisos de lectura/escritura para el _bucket_.
**AVISO:** Se recomienda crear usuarios _IAM_ (Identity and Access Management) que solo tengan permisos de lectura/escritura en el _bucket_ que deseas usar para esa instancia específica de Consul Democracy.
Una vez que tengas esta información, puedes guardarla como variables de entorno de la instancia que ejecuta Consul Democracy. En este tutorial, las guardamos respectivamente como *S3_BUCKET*, *S3_REGION*, *S3_ACCESS_KEY_ID* and *S3_SECRET_ACCESS_KEY*.
```bash
heroku config:set S3_BUCKET=example-bucket-name S3_REGION=eu-west-example S3_ACCESS_KEY_ID=xxxxxxxxx S3_SECRET_ACCESS_KEY=yyyyyyyyyy
```
Ahora añade el siguiente bloque en tu fichero *secrets.yml*:
```yaml
production:
s3:
access_key_id: <%= ENV["S3_ACCESS_KEY_ID"] %>
secret_access_key: <%= ENV["S3_SECRET_ACCESS_KEY"] %>
region: <%= ENV["S3_REGION"] %>
bucket: <%= ENV["S3_BUCKET"] %>
```
## Habilitar el uso de S3 en la aplicación
Primero, agrega la siguiente línea dentro de la clase `class Application < Rails::Application` en el fichero `config/application_custom.rb`:
```ruby
# Store uploaded files on the local file system (see config/storage.yml for options).
config.active_storage.service = :s3
```
Luego, descomenta el bloque de **s3** que encontrarás en el fichero *storage.yml*:
```yaml
s3:
service: S3
access_key_id: <%= Rails.application.secrets.dig(:s3, :access_key_id) %>
secret_access_key: <%= Rails.application.secrets.dig(:s3, :secret_access_key) %>
region: <%= Rails.application.secrets.dig(:s3, :region) %>
bucket: <%= Rails.application.secrets.dig(:s3, :bucket) %>
```
Necesitarás reiniciar la aplicación para aplicar los cambios.