Skip to main content

mtls

Setting up and configuring mTLS certificate for Platform OneEntry using tokens and mTLS, as well as deploying the application on a server with Nginx, Docker, and GitLab

Part 1: Setting up mTLS​

Protecting the API​

  1. Using Token: Generate a token in the OneEntry settings and add it to the request headers with the 'x-app-token' parameter, where the value is the token.
  2. Using mTLS: Enable the mTLS option in your OneEntry dashboard and generate the certificate in the OneEntry settings.

Setting up the certificate​

  1. In your dashboard, go to the 'Access' tab and switch from token to mTLS.
  2. Generate a new certificate in OneEntry ('Settings' -> 'Application Certificates' -> 'Create New Certificate').
  3. Download it to your computer and extract it to the 'cert' folder in the root of your project.

Setting up the local environment (using ReactJS as an example)​

  1. Download the setupProxy.js file and save it in the 'src' folder.
  2. Edit the 'target' parameter, specifying the address of your project.
  3. Install the 'http-proxy-middleware' package: 'npm install http-proxy-middleware'.
  4. Start the application.

Part 2: Server Configuration​

Preparing the Server​

  1. Update repository information: apt update.
  2. Add the Docker repository and install packages: apt install nginx certbot docker-ce pwgen.

UFW Configuration​

  1. Block all incoming connections: ufw default deny incoming.
  2. Allow all outgoing connections: ufw default allow outgoing.
  3. Allow incoming TCP connections on ports 22, 80, and 443: ufw allow 22,80,443/tcp.

SSH Configuration​

  1. Edit the SSH daemon configuration: nano /etc/ssh/sshd_config.
  2. Set PasswordAuthentication no.
  3. Restart the SSH daemon: systemctl restart ssh.

Nginx Configuration​

  1. Remove the default configuration file: rm /etc/nginx/sites-available/default.
  2. Create a new configuration file: nano /etc/nginx/sites-available/my_app.
  3. Download and edit the Nginx configuration from OneEntry, replacing "your_domain.com" with your domain.
  4. Then run the command: ‘ln -s /etc/nginx/sites-available/my_app /etc/nginx/sites-enabled', replacing "my_app" with the name of your configuration file.
  5. Issue SSL certificates using Certbot: certbot certonly --webroot -w /var/www/html -d your_domain.
  6. Check automatic certificate renewal: certbot renew --dry-run.
  7. Edit the Certbot cron task to automatically reload Nginx configuration after certificates issuance: ‘nano /etc/cron.d/certbot', replacing the last line with: echo "0 */12 * * * root certbot -q renew && nginx -s reload" > /etc/cron.d/certbot.
  8. Uncomment lines in the configuration file 'nano /etc/nginx/sites-available/my_app' (where 'my_app' is the name of your configuration file).
  9. Check Nginx configuration: nginx -t.
  10. Reload Nginx after each change: nginx -s reload.

Part 3: Deploying the Application with GitLab and GitHub​

GitHub

Creating a new user for GitHub Runner​

  1. Generate a password: 'pwgen -s 15 1'.
  2. Create a new user: 'useradd -m github-runner'.
  3. Set a password for it: 'passwd github-runner'.
  4. Add the new user to groups: 'usermod -aG docker github-runner' and 'usermod -aG sudo github-runner'.
  5. Change the shell for the GitHub Runner user: 'chsh -s /bin/bash github-runner'.
  6. Switch to the new user: 'sudo su - gitlab-runner'.

Configuring GitHub Runner​

  1. Create a GitHub Runner: go to the settings of your repository, click on 'Actions' and select 'Runners', then click on 'New self-hosted runner'.
  2. Follow the instructions in the 'Download' block and the first command in the 'Configure' block.
  3. Add the Runner to system autostart: 'sudo ./svc.sh install'. You will need to enter the password generated earlier.
  4. Start the Runner: 'sudo ./svc.sh start'.
  5. Go to the 'Actions' section, click on 'Runners', and make sure the 'Runner' is running.
  6. Switch back to the 'root' user.
  7. Create a working directory: 'mkdir -p /var/apps/frontend'.
  8. Set permissions for the user 'github-runner': 'chown -R github-runner:docker /var/apps/frontend'.

Configuring environment variables in GitHub​

  1. Create variables DOMAIN, MTLS_USER_CERT, and MTLS_USER_KEY in your GitHub repository ('Settings' -> 'Secrets and Variables').
  2. Generate a certificate in OneEntry, add the certificate and key to the variables. In the DOMAIN variable, specify the address of your project without https.
  3. Download the file docker-compose.yml and two archives .github and .docker.
  4. Put docker-compose.yml, .github.zip, and .docker.zip in the root folder of your project and extract the archives (you can delete the archives after extraction).
  5. Run the push command in your project.
  6. Check the process in the 'Actions' tab.
  7. Check the accessibility of the application in the browser.
GitLab

Registering GitLab Runner​

  1. Specify tags 'docker, frontend'.
  2. Go to 'Settings -> CI/CD -> Runners' and click on the 'New project runner' button.
  3. Go to the created directory: cd /var/apps/gitlab-runner.
  4. Run the command to start the registration process: docker compose run runner register.
  5. Enter the GitLab URL, for example, https://gitlab.com/.
  6. Get the registration token from GitLab (in the 'Runners' section of the project) and paste it into the terminal.
  7. Specify the executor as 'docker'.
  8. Specify the default image as docker:20.10.16.

Setting environment variables in GitLab​

  1. Create variables DOMAIN, MTLS_USER_CERT, and MTLS_USER_KEY in your GitLab repository ('Settings' -> 'CI/CD' -> 'Variables').
  2. Generate a certificate in OneEntry, add the certificate and key to the variables, and specify the address of your project without https in the DOMAIN variable.
  3. Download the files docker-compose.yml, .gitlab-ci.yml, and the .docker archive, place the files in the root of your project, and unpack the archives (you can delete the archives after unpacking).

Preparing GitLab Runner (Docker executor) configuration​

  1. Create the necessary directories: mkdir -p /var/apps/gitlab-runner/volumes/etc/gitlab-runner.
  2. Run the command: cat /var/apps/gitlab-runner/docker-compose.yaml version: '3' services: runner: image: 'gitlab/gitlab-runner:v16.2.0' restart: always container_name: 'gitlab-runner' privileged: true volumes: - './volumes/etc/gitlab-runner:/etc/gitlab-runner' - '/var/run/docker.sock:/var/run/docker.sock' EOT.

GitLab Runner Configuration​

  1. Edit the configuration file: nano volumes/etc/gitlab-runner/config.toml.
  2. Set the privileged parameter to true to enable Docker-in-Docker.
  3. Change the value of volumes to ['/var/run/docker.sock:/var/run/docker.sock', '/cache'] for Docker to work correctly.
  4. Add user = 'gitlab-runner' at the beginning of the file to run the Runner as that user.
  5. Save the changes and exit the editor.
  6. Restart the Runner: 'systemctl restart gitlab-runner'.

Activating and verifying GitLab Runner​

  1. Run the command docker compose up -d to start the Runner.
  2. Go to GitLab and check that the Runner is active and running (you should see its status in the 'Runners' section of the project).

Setting up an additional Runner on the host (shell executor)​

  1. Follow the Instructions to install an additional Runner that runs directly on the host (not in Docker).
  2. Set tags for the Runner: 'shell, frontend'.

Runner Permissions​

  1. Add a new user to the group: 'usermod -aG docker gitlab-runner'.
  2. If you need to change the owner and groups for a file or directory: 'chown -R gitlab-runner:docker /var/apps/frontend'.

Final Configuration and Testing​

  1. Make sure all Runners are properly configured and ready to use.
  2. Execute the push command in your project.
  3. Check the progress in 'Build' -> 'Pipelines'.
  4. Check the availability of the application in the browser.

Conclusion​

Follow these steps for successful setup and deployment of your application with OneEntry. Good luck with development!