mtls

How to set up an mTLS certificate for OneEntry, protect the API with tokens or mTLS, and deploy the application to a server with Nginx, Docker, and GitLab.

Part 1: Setting up mTLS

Protecting the API

1. Token: generate a token in the OneEntry settings and add it to the request headers as the 'x-app-token' parameter.
2. mTLS: enable the mTLS option in your OneEntry dashboard and generate a certificate in the OneEntry settings.

Setting up the certificate

info

The 'Application Certificates' tab appears in the OneEntry settings only after mTLS is enabled for the project. While mTLS is off, the settings show the 'App tokens' tab instead.

1. In your dashboard, open the 'Access' tab and switch from token to mTLS.
2. Generate a new certificate in OneEntry: open 'Settings' -> 'Application Certificates', enter a name in the 'Application name' field of the 'Generate certificates for the application' card, and click 'Create'.
3. Download the certificate and extract it to the 'cert' folder in your project root.

Setting up the local environment (ReactJS example)

1. Download the setupProxy.js file and save it to the 'src' folder.
2. In the 'target' parameter, specify your project's address.
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 the repository information: `apt update`.
2. Add the Docker repository and install the 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. Delete 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 the Nginx configuration from OneEntry and replace "your_domain.com" with your domain.
4. Run '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 with 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 so that Nginx reloads its configuration automatically after certificates are issued: 'nano /etc/cron.d/certbot'. Replace the last line with: `echo "0 */12 * * * root certbot -q renew && nginx -s reload" > /etc/cron.d/certbot`
8. Uncomment the lines in the configuration file: 'nano /etc/nginx/sites-available/my_app' (where 'my_app' is the name of your configuration file).
9. Check the 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 its password: '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: in your repository settings, click 'Actions', select 'Runners', and click 'New self-hosted runner'.
2. Follow the instructions in the 'Download' block and run the first command in the 'Configure' block.
3. Add the Runner to system startup: 'sudo ./svc.sh install'. Enter the password you generated earlier.
4. Start the Runner: 'sudo ./svc.sh start'.
5. In the 'Actions' section, click '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 'github-runner' user: 'chown -R github-runner:docker /var/apps/frontend'.

Configuring environment variables in GitHub

1. In your GitHub repository, create the `DOMAIN`, `MTLS_USER_CERT`, and `MTLS_USER_KEY` variables ('Settings' -> 'Secrets and Variables').
2. Generate a certificate in OneEntry and add the certificate and key to the variables. In the `DOMAIN` variable, specify your project's address without https.
3. Download the docker-compose.yml file and two archives, .github and .docker.
4. Put docker-compose.yml, .github.zip, and .docker.zip in your project's root folder and extract the archives (you can delete the archives afterward).
5. Push your project.
6. Track the process in the 'Actions' tab.
7. Check that the application is available in the browser.

GitLab

Registering GitLab Runner

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

Setting environment variables in GitLab

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

Preparing the GitLab Runner configuration (Docker executor)

1. Create the required directories: `mkdir -p /var/apps/gitlab-runner/volumes/etc/gitlab-runner`
2. Run: `cat \ /var/apps/gitlab-runner/docker-compose.yamlversion: '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. To enable Docker-in-Docker, set the `priviledged` parameter to `true`.
3. For Docker to work correctly, change the value of `volumes` to `['/var/run/docker.sock:/var/run/docker.sock', '/cache']`.
4. To run the Runner as the 'gitlab-runner' user, add `user = 'gitlab-runner'` at the beginning of the file.
5. Save the changes and exit the editor.
6. Restart the Runner: 'systemctl restart gitlab-runner'.

Activating and verifying GitLab Runner

1. Start the Runner: `docker compose up -d`.
2. In GitLab, check that the Runner is active and running (its status appears in the project's 'Runners' section).

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 the Runner tags: 'shell, frontend'.

Runner permissions

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

Final configuration and testing

1. Make sure all Runners are configured correctly and ready to use.
2. Push your project.
3. Track the progress in 'Build' -> 'Pipelines'.
4. Check that the application is available in the browser.

Conclusion

Follow these steps to set up and deploy your application with OneEntry.