workshops.md

workshops.md

How to get "Workshops" Rails application up and running on your local machine for development.

Goal: Set up a local development environment for the Workshops application using Docker.

1. Prerequisites:

• Git: To clone the repository.
• Docker: To build and run containerized applications. (Install Docker)
• Docker Compose: To manage multi-container Docker applications. It's usually included with Docker Desktop.

2. Clone the Repository:

git clone <repository-url> workshops
cd workshops

Replace <repository-url> with the actual URL of your Git repository.

3. Configuration Setup:

This application uses several configuration files provided as examples. You need to copy them to their actual names and customize them.

• Copy .example files: The README.md and entrypoint.sh.example mention several .example files. The most crucial ones for Docker setup are:

  • docker-compose.yml.example -> docker-compose.yml
  • Dockerfile.example -> Dockerfile
  • entrypoint.sh.example -> entrypoint.sh
  • nginx.conf.erb.example -> nginx.conf.erb (Used by Passenger within Docker)
  • Passengerfile.json.example -> Passengerfile.json (Used by Passenger)
  • config/initializers/custom_env.rb.example -> config/initializers/custom_env.rb (While Docker uses docker-compose.yml for environment variables, having this file copied is good practice for Rails development awareness, though potentially less critical inside the Docker flow if docker-compose.yml defines everything).

  You can copy them using:

  cp docker-compose.yml.example docker-compose.yml
  cp Dockerfile.example Dockerfile
  cp entrypoint.sh.example entrypoint.sh
  # Make entrypoint executable
  chmod +x entrypoint.sh
  cp nginx.conf.erb.example nginx.conf.erb
  cp Passengerfile.json.example Passengerfile.json
  cp config/initializers/custom_env.rb.example config/initializers/custom_env.rb

• Review docker-compose.yml:

  • Purpose: Defines the services needed to run the application (web server, database, background job worker).
  • Action: Open docker-compose.yml. Pay close attention to the environment: sections for the db, web, and que services.
  • Crucially: Change the default passwords (like POSTGRES_PASSWORD, DB_PASS) and secret keys (SECRET_KEY_BASE, DEVISE_SECRET_KEY, etc.) to secure, random values. You can generate secrets using commands like openssl rand -hex 64 or rake secret.
  • Review port mappings (e.g., 8000:8000 means host port 8000 maps to container port 8000).
  • Review volume mappings. It seems set up to mount your local code into the container (./:/home/app/workshops) which is good for development. It also uses named volumes (pgdata, rubygems) for database data and gems to persist them and potentially improve performance on some systems (like macOS).

• Review Dockerfile:

  • Purpose: Provides instructions to build the Docker image for the web and que services. It specifies the base image, installs system dependencies (like postgresql-client, nodejs, yarn), sets up Ruby, copies application code, and installs gems/packages.
  • Action: You probably don't need to change this initially, but understand it's how the application's environment inside the container is defined.

• Review entrypoint.sh:

  • Purpose: This script runs inside the web container when it starts up (docker compose up). It performs essential setup tasks.
  • Action: Read through it. You'll see it:
    • Installs Ruby gems (bundle install).
    • Runs database migrations (rails db:migrate).
    • Initializes application settings (rake ws:init_settings). Important: This populates the settings table with defaults defined in lib/tasks/init-settings.rake. It's crucial for the first run.
    • Creates admin users (rake ws:create_admins or birs:create_admins). Important: Check lib/tasks/ws.rake (or birs.rake if it exists) for the default credentials it creates. You'll need these to log in initially.
    • Installs JS dependencies (yarn install).
    • Precompiles assets (rake assets:precompile).
    • Starts the Rails server using Passenger.
  • Note: For subsequent runs after the first successful setup, you might comment out db:migrate, init_settings, and create_admins in your local entrypoint.sh if you don't want them running every time, although migrations are often safe to run repeatedly.

• Review entrypoint-que.sh:

  • Purpose: Runs inside the que container to start the Que background job worker.
  • Action: Usually doesn't need changes initially.

4. Build and Run with Docker Compose:

• Build the Image: Open your terminal in the project's root directory (workshops/) and run:

  docker compose build

  This command reads the Dockerfile and builds the Docker image needed for the web and que services. This might take a while the first time as it downloads the base image and installs dependencies.

• Create Docker Volumes (if using named volumes and they don't exist): The docker-compose.yml.example mentions creating data volumes manually beforehand, especially for performance on macOS. If you stick with the named volumes (pgdata, rubygems), Docker Compose should create them automatically on the first up. If you encounter issues, you might need to create them manually as hinted in the comments of docker-compose.yml.example:

  # Example commands (adapt image tags if needed):
  # docker volume create --name=workshops_pgdata
  # docker volume create --name=workshops_rubygems
  # Then update docker-compose.yml to use these external volumes if desired.
  # For now, rely on docker compose creating them automatically.

• Start the Application:

  docker compose up

  This command does the following:

  1. Creates and starts containers for the services defined in docker-compose.yml (db, web, que).
  2. Runs the database initialization scripts found in db/pg-init/ inside the db container (this happens only the first time the db container starts with an empty data volume). It creates the databases and the user specified in your docker-compose.yml environment variables.
  3. Runs the /sbin/entrypoint.sh script inside the web container. This performs the Rails setup (gems, migrations, settings, admins, assets).
  4. Runs the /sbin/entrypoint-que.sh script inside the que container to start the background worker.
  5. Attaches your terminal to the logs of all containers. You'll see output from the database, Rails server, and Que worker.

  Troubleshooting: If docker compose up fails, carefully read the error messages. Common issues include: * Incorrect passwords/secrets in docker-compose.yml. * Port conflicts (if port 8000 or 5432 is already in use on your host). * Errors during bundle install or db:migrate. * File permission issues (less common with Docker volume mounts now, but possible).

5. Access the Application:

• Once the entrypoint.sh script finishes and you see messages indicating the Passenger server has started, open your web browser and navigate to http://localhost:8000 (or whatever host/port you configured).

6. Initial Login:

• You should see the login page.
• Log in using the credentials for the admin user created by the rake ws:create_admins (or birs:create_admins) task run by entrypoint.sh. Check the definition of that task in lib/tasks/ws.rake (or birs.rake) for the default email/password if you didn't change it.
• After logging in as an admin, navigate to /settings (usually via a user dropdown menu) to review and adjust application settings stored in the database.

7. Development:

• Your local code directory is mounted into the container. Changes you make locally should be reflected when you refresh the browser (Rails development mode usually handles code reloading). For changes to assets or configuration, you might need to restart the containers (docker compose down && docker compose up).
• Running Rake Tasks/Console: Open a new terminal window and run:

  docker compose exec web bash

  This gives you a shell inside the running web container. From there you can run rails c, rake -T, bundle exec rspec, etc.
• Database: The database is running in its own container (db). You can connect to it using standard PostgreSQL tools if needed, using the credentials and host (db) defined in docker-compose.yml.