Skip to content

Devops documentation

Jump to bottom
João Heytor Kreitlow Pereira edited this page Apr 4, 2025 · 1 revision

Current pipeline

The project uses a CI/CD pipeline to automate builds, tests, and deployments via GitHub Actions. The configuration is stored in the workflow file: docker-build-push-redeploy.yml.

The pipeline handles Docker image builds, pushing to a registry, and redeploying instances when changes are detected.

Step-by-Step Guide for Setting Up New Server

Follow these steps to set up a new server:

1. Create New Server

  • Server Name: brain-up-new
  • Configuration: Ubuntu 22.04, 512MB Memory, 20GB SSD, 1CPU

Install Docker

sudo apt update
sudo apt install docker.io

Install Docker-Compose

sudo apt install docker-compose

Install GitHub Self-Hosted Runner

Copy Database from Old Instance

  • Investigate the current database migration process to ensure all data is transferred accurately

Register New Domain Name

  • Create and configure the domain name for the new server

Create Pipelines for New Instance Deployment

  • Ensure that new pipeline steps are set up to deploy to the newly created server
  • Ensure the configuration for Docker and deployment variables is updated accordingly

Verify Deployment

  • Use the docker ps -a command to check running containers
  • Review logs with docker logs brn

Server Logs and Monitoring

To monitor and debug the application, you’ll need to inspect the logs and running containers. This will help you ensure everything is running smoothly and troubleshoot any issues that arise.

View Running Containers

docker ps -a

This will list all containers, including ones like brn, brn_fe, and brn_db_brn_1, which are essential for the system to function properly.

View Logs

Use the following command to view logs from a specific container:

docker logs <container_name>

For example, to view logs for the main application container (brn), you can run:

docker logs brn

However, depending on the issue, it can be helpful to focus on error messages. You can use the grep command to filter the logs and search for specific keywords like “ERROR”:

docker logs brn | grep ERROR

This will display only the lines that contain the word “ERROR”, helping you quickly identify issues in the logs. You can replace “ERROR” with other terms like “WARNING” or “INFO” based on the kind of logs you’re looking for.

Debugging Multiple Containers

Since the system involves multiple containers, it’s important to check the logs for other related containers, such as:
- brn_fe: The frontend container
- brn_db_brn_1: The database container

For instance, to view the logs of the frontend container, use:

docker logs brn_fe

Similarly, for database logs, run:

docker logs brn_db_brn_1

This way, you can debug issues related to specific parts of the system (e.g., frontend, database, or application).

Additional Debugging Tips

  1. Interactive Shell: If you need to troubleshoot within a container, you can open an interactive shell:
docker exec -it <container_name> /bin/bash

This allows you to run commands directly inside the container, which can be useful for inspecting configuration files, environment variables, or running tests.

  1. Tail Logs: For real-time monitoring of log output, you can “tail” the logs. This will show new log entries as they are added:
docker logs -f brn

The -f flag keeps the logs open, so you can monitor them continuously, which is especially useful during debugging sessions.

  1. Check Container Health: Sometimes, the issue might be related to a container’s health. You can inspect the container’s health status using:
docker inspect --format '{{json .State.Health}}' <container_name>

This can help you identify if the container has failed any health checks.

Overview of Available Dockerfiles

The repository contains several Dockerfiles, each serving a specific purpose:

  • Dockerfile: This is the primary Dockerfile used for building the main application image. It sets up the environment and installs necessary dependencies 
  • Dockerfile_frontend: Tailored for building the frontend component of the application
  • Dockerfile_frontend_with_tls: Similar to Dockerfile_frontend but includes configurations for TLS (Transport Layer Security), ensuring secure data transmission
  • Dockerfile_test: Designed for running tests, setting up an environment suitable for executing the project’s test suite

Building and Running the Application Locally

To run the application locally, follow these steps:

Clone the Repository

Begin by cloning the repository to your local machine:

git clone https://github.com/Brain-up/brn.git
cd brn

Build the Docker Image

Use the primary Dockerfile to build the application image:

docker build -t brain-up-app .

This command reads the Dockerfile in the current directory, installs dependencies, and sets up the application environment.

Run the Application

After building the image, run it as a container:

docker run -p 8080:8080 brain-up-app

This maps port 8080 of the container to port 8080 on your local machine, allowing you to access the application at http://localhost:8080.

Running Tests Locally

To execute the project’s test suite:

Build the Test Image

Use the Dockerfile_test to create a testing environment:

docker build -f Dockerfile_test -t brain-up-test .

Run the Tests

Execute the tests using the built image:

docker run --rm brain-up-test

The --rm flag ensures that the container is removed after the tests have completed.

Additional Considerations

Frontend Development

If you’re focusing on frontend development and need to build the frontend image:

docker build -f Dockerfile_frontend -t brain-up-frontend .

For a secure TLS-enabled frontend setup:

docker build -f Dockerfile_frontend_with_tls -t brain-up-frontend-tls .

Environment Variables

Ensure that any required environment variables are set. You can define them in a .env file or pass them directly when running the container:

docker run --env-file .env -p 8080:8080 brain-up-app

Database Setup

The application requires a PostgreSQL database. It’s recommended to use Docker Compose to set up both the application and the database services:

Create a docker-compose.yml File

Define the services, networks, and volumes in this file to streamline the setup process.

Start the Services:
docker-compose up --build

This command builds and starts both the application and database containers.

Accessing the Application

Once the application is running, access it via your web browser at http://localhost:8080. Ensure that the backend and frontend are correctly configured to communicate with each other.

Stopping the Services

To stop the running containers:

docker-compose down

This command stops and removes all containers defined in the docker-compose.yml file.

Troubleshooting

Logs

View logs for a specific container:

docker logs <container_name>

Interactive Shell

Access an interactive shell within a running container:

docker exec -it <container_name> /bin/bash

Additional Resources

Clone this wiki locally