workshops_start.md

Steps to Set Up BIRS Workshops with Docker

1. Clone the repository (if you haven't already):

   git clone https://github.com/birs-math/workshops.git
   cd workshops

2. Copy the example configuration files to create your actual configuration files:

   for file in `ls -1 *.example`; do 
     newfile=`echo $file | sed 's/\.example$//'`
     cp $file $newfile
   done

   This should create the following files from their .example templates:

   • docker-compose.yml
   • Dockerfile
   • entrypoint.sh
   • nginx.conf.erb
   • Passengerfile.json

3. Make sure entrypoint.sh is executable:

   chmod +x entrypoint.sh

4. Edit the docker-compose.yml file to configure:

   • Environment variables
   • Secure passwords
   • Database configuration
   • Persistent storage volumes

   The docker-compose.yml should include services for:

   • PostgreSQL database (db)
   • Web application (web)

5. Create data containers (if using the recommended approach):

   # For PostgreSQL data
   docker run -v /var/lib/postgresql/data --name pgdata postgres:11.2 echo 'Postgres data'
   
   # For Ruby gems
   docker run -v /usr/local/rvm/gems -v /home/app/workshops/vendor/cache \
       --name rubygems "phusion/passenger-ruby26:1.0.10" echo 'Ruby gems'

6. Edit lib/tasks/ws.rake to set your admin credentials.

7. Configure environment variables in the docker-compose.yml:

   • DB_USER and DB_PASS
   • Security keys (SECRET_KEY_BASE, DEVISE_SECRET_KEY, etc.)
   • Email configuration
   • Application host settings

8. Run the docker build and start containers:

   docker-compose build
   docker-compose up -d

9. Initialize the database if needed (inside the container):

   docker exec -it ws bash
   # Inside the container:
   rake db:schema:load
   rake ws:init_settings
   rake ws:create_admins
   # Optionally add seed data:
   rake db:seed

10. Access the web interface at http://localhost

Common Issues and Solutions

Here are some potential issues you might be facing:

1. Permission problems:

   • Ensure entrypoint.sh and other scripts are executable
   • Check ownership of volumes/directories

2. Database connection issues:

   • Verify PostgreSQL is running and accessible
   • Check if the database users and passwords match in all config files

3. Docker network problems:

   • Ensure the containers can communicate with each other
   • Check ports in docker-compose.yml

4. Ruby/Rails compatibility:

   • Check if you're using compatible versions of Ruby and Rails

5. Volume mount issues:

   • Ensure your volume mounts are correctly configured

6. Configuration mismatches:

   • Make sure environment variables are consistent across files

Let me know if you've already tried any of these steps or if you're encountering specific error messages when running docker-compose build or docker-compose up -d. With more information about the specific errors, I can provide more targeted help.