feat: Add Docker setup for local development

Dockerfile

@@ -1,18 +1,20 @@
-FROM ruby:3.1-slim
+FROM ruby:3.4.2
 
-ENV RACK_ENV=production
-ENV LANG=en_US.UTF-8
+RUN apt-get update -qq && apt-get install -y build-essential libpq-dev cron
 
-RUN apt update && apt install -y \
-  build-essential libpq-dev  \
-  && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
 
-# Install deps
-ADD Gemfile Gemfile.lock ./
+COPY Gemfile Gemfile.lock ./
 
 RUN bundle install
 
-ADD . .
+COPY update_sepomex.sh /app/update_sepomex.sh
+COPY cron/sepomex_update_cron /etc/cron.d/sepomex_update_cron
+RUN chmod +x /app/update_sepomex.sh
+RUN chmod 0644 /etc/cron.d/sepomex_update_cron
 
-# run server
-CMD bundle exec puma -p ${PORT:-3000} -e ${RACK_ENV:-development}
+COPY . .
+
+EXPOSE 3000
+
+CMD ["bundle", "exec", "puma", "-p", "3000", "-e", "development"]

Gemfile

@@ -3,6 +3,8 @@
 source 'https://rubygems.org'
 ruby '3.4.2'
 
+gem 'csv'
+
 gem 'activerecord'
 gem 'cuba'
 gem 'dalli'

Gemfile.lock

@@ -26,6 +26,7 @@ GEM
     bigdecimal (3.1.9)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.0)
+    csv (3.3.2)
     cuba (4.0.3)
       rack (>= 3.0.0)
       rack-session (>= 2.0.0)
@@ -116,6 +117,7 @@ PLATFORMS
 
 DEPENDENCIES
   activerecord
+  csv
   cuba
   dalli
   database_cleaner-active_record

Readme.md

@@ -1,29 +1,92 @@
 # API para los códigos postales de México
-[![Code Climate](https://codeclimate.com/github/Munett/API-Codigos-Postales/badges/gpa.svg)](https://codeclimate.com/github/Munett/API-Codigos-Postales)
 
-[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/acrogenesis/API-Codigos-Postales)
+[](https://codeclimate.com/github/Munett/API-Codigos-Postales)
 
-Dado un código postal, regresa un arreglo con las colonia, municipio y estado perteneciente al código postal.
-Además se pueden realizar búsquedas de códigos postales usando los números iniciales.
+[](https://heroku.com/deploy?template=https://github.com/acrogenesis/API-Codigos-Postales)
 
-## Sube la app a heroku
-1) Da click en el botón `Deploy to Heroku` y sigue los pasos.
-2) Al terminar corre `heroku run rake sepomex:update`.
-3) Agrega el task de `rake sepomex:update` en el addon de Heroku
-Scheduler para que se corra cada día.
+Dado un código postal, regresa un arreglo con las colonias, municipio y estado perteneciente al código postal. Además, se pueden realizar búsquedas de códigos postales usando los números iniciales.
+
+## Sube la app a Heroku
+
+1)  Da click en el botón `Deploy to Heroku` y sigue los pasos.
+2)  Al terminar corre `heroku run rake sepomex:update`.
+3)  Agrega el task de `rake sepomex:update` en el addon de Heroku Scheduler para que se corra cada día.
+
+## Running with Docker Compose
+
+This project can be easily run using Docker Compose, which sets up the Ruby application, a PostgreSQL database, and a cron job for data updates.
+
+**Prerequisites:**
+
+  * Docker and Docker Compose installed on your system.
+
+**Steps:**
+
+1.  **Clone the repository and navigate into the directory.**
+
+2.  **Build and start all services in the background:**
+    This command builds the images if they don't exist and starts the `db`, `web`, and `cron_worker` containers.
+
+    ```bash
+    docker compose up -d --build
+    ```
+
+3.  **Check the status of the containers:**
+    Wait for the `db` service to show `(healthy)` in the status column before proceeding.
+
+    ```bash
+    docker compose ps
+    ```
+
+4.  **Run database migrations:**
+    This command sets up the necessary tables in the database.
+
+    ```bash
+    docker compose run --rm web bundle exec rake db:migrate
+    ```
+
+5.  **Seed the database with postal code data:**
+    This step downloads and imports the latest postal code data from SEPOMEX. It might take some time.
+
+    ```bash
+    docker compose run --rm web bundle exec rake sepomex:update
+    ```
+
+6.  **Access the application:**
+    The API should now be running and available at `http://localhost:3000`.
+
+## Scheduled Data Updates (Cron Job)
+
+The `cron_worker` service is configured to automatically run `rake sepomex:update` every day at 3:00 AM (UTC) to keep the postal code data fresh.
+
+**How to Verify the Cron Job:**
+
+1.  **Check the `cron_worker` logs:**
+    ```bash
+    docker compose logs -f cron_worker
+    ```
+    You will see output from the cron daemon and the rake task when it executes.
+
+**How to Manually Trigger an Update:**
+
+To run the update process immediately without waiting for the scheduled time, execute the rake task directly on the `web` service (as it has the application code and dependencies):
+
+```bash
+docker compose run --rm web bundle exec rake sepomex:update
+```
 
 ## Suscripción y documentación de la API
 
 [https://rapidapi.com/acrogenesis-llc-api/api/mexico-zip-codes](https://rapidapi.com/acrogenesis-llc-api/api/mexico-zip-codes)
 
-
 **Consultar la información de un código postal**
 
 ```text
 https://mexico-zip-codes.p.rapidapi.com/codigo_postal/66436
 ```
 
 **Respuesta del servidor**
+
 ```json
 {
   "codigo_postal": "66436",
@@ -36,37 +99,42 @@ https://mexico-zip-codes.p.rapidapi.com/codigo_postal/66436
 }
 ```
 
----
+-----
 
 **Buscar códigos postales**
 
 ```text
 https://mexico-zip-codes.p.rapidapi.com/buscar
 ```
 
-_parámetros necesarios_
+*parámetros necesarios*
+
 ```text
   codigo_postal=# codigo a buscar, parcial o total
 ```
 
-_parámetros opcionales_
+*parámetros opcionales*
+
 ```text
   limit=# número máximo de resultados a devolver
 ```
 
-_Ejemplo de búsqueda para códigos que inicien con **66**, con **664** y con **6641**_
-```json
+*Ejemplo de búsqueda para códigos que inicien con **66**, con **664** y con **6641***
+
+```text
 https://mexico-zip-codes.p.rapidapi.com/buscar?codigo_postal=66
 https://mexico-zip-codes.p.rapidapi.com/buscar?codigo_postal=664
 https://mexico-zip-codes.p.rapidapi.com/buscar?codigo_postal=6641
 ```
 
-_Ejemplo de búsqueda limitada a 3 resultados_
-```json
+*Ejemplo de búsqueda limitada a 3 resultados*
+
+```text
 https://mexico-zip-codes.p.rapidapi.com/buscar?codigo_postal=66&limit=3
 ```
 
-** Para el código postal 6641 el servidor regresa **
+\*\* Para el código postal 6641 el servidor regresa \*\*
+
 ```json
 {
   "codigos_postales": [
@@ -81,42 +149,36 @@ https://mexico-zip-codes.p.rapidapi.com/buscar?codigo_postal=66&limit=3
 }
 ```
 
----
+-----
 
 **Buscar códigos postales por ubicación**
 
 ```text
 https://mexico-zip-codes.p.rapidapi.com/v2/buscar_por_ubicacion
 ```
 
-_parámetros necesarios_
+*parámetros necesarios*
+
 ```text
   estado=# nombre del estado
   municipio=# nombre del municipio
 ```
 
-_parámetros opcionales_
+*parámetros opcionales*
+
 ```text
   colonia=# nombre de la colonia (opcional)
   limit=# número máximo de resultados a devolver
 ```
 
-_Ejemplo de búsqueda para códigos postales en Nuevo León, San Nicolás de los Garza_
-```text
-https://mexico-zip-codes.p.rapidapi.com/v2/buscar_por_ubicacion?estado=Nuevo%20León&municipio=San%20Nicolás%20de%20los%20Garza
-```
-
-_Ejemplo de búsqueda para códigos postales en Nuevo León, San Nicolás de los Garza, colonia Praderas de Santo Domingo_
-```text
-https://mexico-zip-codes.p.rapidapi.com/v2/buscar_por_ubicacion?estado=Nuevo%20León&municipio=San%20Nicolás%20de%20los%20Garza&colonia=Praderas%20de%20Santo%20Domingo
-```
+*Ejemplo de búsqueda para códigos postales en Nuevo León, San Nicolás de los Garza*
 
-_Ejemplo de búsqueda limitada a 5 resultados_
 ```text
-https://mexico-zip-codes.p.rapidapi.com/v2/buscar_por_ubicacion?estado=Nuevo%20León&municipio=San%20Nicolás%20de%20los%20Garza&limit=5
+https://mexico-zip-codes.p.rapidapi.com/v2/buscar_por_ubicacion?estado=Nuevo%20León&municipio=San%20Nicolás%20de%20los%20Garza
 ```
 
 **Respuesta del servidor**
+
 ```json
 {
   "codigos_postales": [
@@ -125,18 +187,24 @@ https://mexico-zip-codes.p.rapidapi.com/v2/buscar_por_ubicacion?estado=Nuevo%20L
 }
 ```
 
-___
+-----
 
 ### Rake task
-Ejecuta el rake task `rake sepomex:update` para descargar todos los códigos postales de México y actualizar tu base de datos.
+
+Ejecuta el rake task `rake sepomex:update` para descargar todos los códigos postales de México y actualizar tu base de datos. When running with Docker Compose, use the correct service name:
+
+```bash
+docker compose run --rm web bundle exec rake sepomex:update
+```
 
 ### Colabora
-Errores y pull requests son bienvenidos en Github: https://github.com/Munett/API-Codigos-Postales.
-Para bajar en tu BD todos los códigos postales corre el rake script `rake sepomex:update`.
 
-Los datos se obtuvieron de http://www.correosdemexico.gob.mx/lservicios/servicios/CodigoPostal_Exportar.aspx
+Errores y pull requests son bienvenidos en Github: [https://github.com/Munett/API-Codigos-Postales](https://github.com/Munett/API-Codigos-Postales).
+
+Los datos se obtuvieron de [http://www.correosdemexico.gob.mx/lservicios/servicios/CodigoPostal\_Exportar.aspx](http://www.correosdemexico.gob.mx/lservicios/servicios/CodigoPostal_Exportar.aspx)
 
 ### Los datos se actualizan cada domingo.
 
 ### Licencia
-MIT License
+
+MIT License

cron/sepomex_update_cron

@@ -0,0 +1 @@
+0 3 * * * /app/update_sepomex.sh >> /var/log/cron.log 2>&1

docker-compose.yml

@@ -0,0 +1,64 @@
+version: '3.8'
+
+services:
+  db:
+    image: postgres:15
+    container_name: codigos-postales-db-test
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: api-codigos-postales
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    networks:
+      - app-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d api-codigos-postales"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  web:
+    build: .
+    container_name: codigos-postales-web-test
+    command: bundle exec puma -p 3000 -e development
+    volumes:
+      - .:/app
+      - gem_cache:/usr/local/bundle/gems
+    ports:
+      - "3000:3000"
+    depends_on:
+      db:
+        condition: service_healthy
+    networks:
+      - app-network
+    environment:
+      RACK_ENV: development
+      DATABASE_URL: postgresql://postgres:password@db:5432/api-codigos-postales
+      VALIDATE_HEADER: X-API-TOKEN
+      VALIDATE_HEADER_VALUE: very-secret-local-token
+
+  cron_worker:
+    build: .
+    container_name: codigos-postales-cron
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      RACK_ENV: development
+      DATABASE_URL: postgresql://postgres:password@db:5432/api-codigos-postales
+    volumes:
+      - .:/app
+      - gem_cache:/usr/local/bundle/gems
+    command: cron -f
+    networks:
+      - app-network
+
+volumes:
+  postgres_data:
+  gem_cache:
+
+networks:
+  app-network:

update_sepomex.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd /app
+bundle exec rake sepomex:update