Installation

Docker compose

The recommended and most convenient way to use Goiabada is via a container. Container images are available in docker hub.

To get started, feel free to use and customize the following docker compose file. You can read more about the environment variables here.

docker-compose.yml

version: '3.8'
services:

  mysql-server:
    image: mysql:latest
    restart: unless-stopped
    ports:
      # host_port:container_port
      - 3100:3306  
    volumes:
      - mysql-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: mySqlPass123
    healthcheck:
      # important: keep user (-u) and password (-p) below in sync 
      # with environment variables GOIABADA_DB_USERNAME, GOIABADA_DB_PASSWORD 
      # and MYSQL_ROOT_PASSWORD      
      test: ["CMD", "mysqladmin", "ping", "-uroot", "-pmySqlPass123",  "--protocol", "tcp"]
      interval: 1s
      timeout: 2s
      retries: 20
    networks: 
      - goiabada-network  

  goiabada:
    image: leodip/goiabada:latest
    restart: unless-stopped
    depends_on: 
      mysql-server:
        condition: service_healthy    
    ports:
      # host_port:container_port
      - 8100:80 # http
      #- 8100:443 # https    
    command: sleep infinity
    networks: 
      - goiabada-network
    environment:
      # See all timezones:
      # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      - TZ=Europe/Lisbon 

      # The email address of the admin user (the first user created)
      - GOIABADA_ADMIN_EMAIL=admin@example.com

      # The password of the admin user (the first user created)
      - GOIABADA_ADMIN_PASSWORD=changeme

      # The name of the application
      - GOIABADA_APPNAME=Goiabada

      # Without TLS (http) - do not use in production!
      - GOIABADA_ISSUER=http://localhost:8100
      - GOIABADA_BASEURL=http://localhost:8100
      - GOIABADA_CERTFILE= #leave this empty to use http
      - GOIABADA_KEYFILE= #leave this empty to use http
      - GOIABADA_HOST= # leave this empty to listen on all available interfaces
      - GOIABADA_PORT=80
      - GOIABADA_RATELIMITER_ENABLED=true # built-in HTTP rate limiter
      - GOIABADA_RATELIMITER_MAXREQUESTS=50 # max requests per time window
      - GOIABADA_RATELIMITER_WINDOWSIZEINSECONDS=10 # time window in seconds

      # # With TLS (https)
      # - GOIABADA_ISSUER=http://localhost:8100
      # - GOIABADA_BASEURL=http://localhost:8100
      # - GOIABADA_CERTFILE=./cert/self_signed_cert.pem #certificate file (for https)
      # - GOIABADA_KEYFILE=./cert/self_signed_key.pem # private key file (for https)
      # - GOIABADA_HOST= # leave this empty to listen on all available interfaces
      # - GOIABADA_PORT=443

      # The directory where the templates and static files are located
      - GOIABADA_TEMPLATEDIR=./web/template #leave this empty to use embedded templates
      - GOIABADA_STATICDIR=./web/static #leave this empty to use embedded static files

      # If you want to use a reverse proxy in front of Goiabada, set this to true
      - GOIABADA_ISBEHINDAREVERSEPROXY=false

      # Database (mysql) details
      - GOIABADA_DB_HOST=mysql-server
      - GOIABADA_DB_PORT=3306
      - GOIABADA_DB_DBNAME=goiabada
      - GOIABADA_DB_USERNAME=root
      - GOIABADA_DB_PASSWORD=mySqlPass123

      # GORM (sql ORM) - trace all SQL: true, false
      - GOIABADA_LOGGER_GORM_TRACEALL=false

      # Http requests logging: true, false
      - GOIABADA_LOGGER_ROUTER_HTTPREQUESTS_ENABLED=true

      # Audit messages in console log: true, false
      - GOIABADA_AUDITING_CONSOLELOG_ENABLED=true

volumes:
  mysql-data:

networks:
  goiabada-network:

If you have Docker working in your environment, save the above file and execute the following command:

docker compose up -d

Once the container is ready, you can access the application using the URL:

http://localhost:8100

The default admin credentials are:

Email: admin@example.com
Password: changeme

Important: the docker compose file given above is set up with HTTP (non-TLS), making it insecure. HTTP should only be used for testing or development purposes.

SSL certs

HTTPS/TLS is essential for Goiabada to function securely. When you have the SSL cert for your domain, remember to make it available to the container, using a volume. Then, amend the environment variables GOIABADA_CERTFILE and GOIABADA_KEYFILE to point to your certification and key files, accordingly. Don't forget to use the correct port in your docker compose file.

You can have a look at the documentation of Docker https://docs.docker.com/compose/compose-file/07-volumes/ for details on how to map a volume.