# Welcome
Welcome to the **SquadDNS Documentation**.
Here you will find everything about the installation and configuration
The tutorial section helps you to get going with all kinds of different scenarios.
Let's start with our first step - the installation!
{% content-ref url="/pages/-MVrkv99vTbXTa4bk0Vm" %}
[Installation](/installation/installation)
{% endcontent-ref %}
# Changelog
## v1.0.0
**Added**
* initial release
* Authentication with BasicAuth + IP allow list
* Domain Record Management
* User Management
# Installation
## 1. Setup Server
Start by setting up a server.\
Docker usually runs best on a Linux system.
{% hint style="warning" %}
Please keep in mind, that these installation steps do not cover any security recommendations. However, it would be good, to only allow the administration panel if you are connected from within your company network (VPN).
{% endhint %}
## 2. Install Docker
SquadDNS is based on Docker.\
Please install Docker for your operating system.
## 3. Run SquadDNS
#### Simple Instance
```bash
docker run -p 80:80 -p 443:443 boxblinkracer/squad-dns:latest
```
#### Persistent Instance
```yaml
version: "3.0"
services:
squad:
container_name: squad-dns
image: boxblinkracer/squad-dns:latest
restart: always
ports:
- 80:80
- 443:443
volumes:
- ./config:/var/www/html/config
```
#### Custom SSL certificates
You can also mount your custom SSL certificates, if you are not using something like Cloudflare. Therefore just overwrite the built-in selfsigned certificates with yours.
```
squad:
container_name: squad-dns
....
volumes:
- ...
- /etc/letsencrypt/live/my-tunnel.my-domain.com/fullchain.pem:/etc/nginx/ssl/selfsigned.crt
- /etc/letsencrypt/live/my-tunnel.my-domain.com/privkey.pem:/etc/nginx/ssl/selfsigned.key
```
## 4. Create DNS Record
It's recommended to use a specific domain for your server.\
You need to set up the correct DNS records, according to the documentation fo your DNS provider.
{% hint style="success" %}
That's it, SquadDNS is now ready for you! \
A simple [setup wizard](/installation/first-run) helps you to get started immediately.
{% endhint %}
�
# Setup Wizard
The first time you open the application you will see a setup wizard to get you started.
### Domain
The domain is used as an additional security layer to access your administration.\
The incoming domain needs to match this one, to enter it.\
Leave empty, if you do not want to use it.
### Administration
Create an administration user to access the application.
{% hint style="success" %}
Perfect! Now let's configure your [first domain](/configuration/domain-management#register-domains).
{% endhint %}
# Update System
SquadDNS is delivered as Docker image.
If there is a new version (visible in the administration), you just need to pull the latest image and restart your Docker containers.
## Backup configuration
First make sure to **backup** your current **configuration** folder and files.
## Download latest image
If you use the **latest** tag, just pull the latest version one more time.
```
docker pull boxblinkracer/squad-dns:latest
```
If you use a specific tag, just make sure to set the new version that you want to use in your docker-compose.yml or docker run command.
```
image: boxblinkracer/squad-dns:1.2.0
```
## Restart Containers
After downloading the latest versions, just restart your Docker containers
```
docker-compose down
docker-compose up -d
```
{% hint style="success" %}
Congratulations, you have just updated to the latest SquadDNS version!
{% endhint %}
# Domain Management
This page shows you how to create new domain records or manage and update the existing ones.
## 1. Register Domains
If you want to onboard a new member of your team, you need to set up a new domain first.
### 1.1 Create Domain (DNS Provider)
SquadDNS is no DNS provider, so it cannot just create new domains that can be used online.\
Please open the DNS management of your provide and create a new record for the developers domain.
This is usually an **A record** that needs to point to the **IP address** of the server where SquadDNS is installed.
Here is a sample screenshot from Cloudflare.
{% hint style="danger" %}
**Attention**, if you only get endless **redirects** later on, try setting the Cloudflare SSL/TLS encryption mode to "**Full**".
{% endhint %}
### 1.2 Add Domain to SquadDNS
Now that your domain has been officially registered, you can add it to SquadDNS.\
Just enter the domain and click on **Add Record**.
Because we have configured our official DNS already, accessing it in the browser will now navigate us to your SquadDNS server, which recognized the domain too, but doesn't have any target assigned.
## 2. Manage Domains
When you start a new tunnel, you usually need to update the **target of your domain**.
SquadDNS gives you a simple overview of all registered domains.
#### Updating Target
Every line comes with a **textfield for the target**, that you can use to enter your new tunnel domain.
#### Enable / Disable
You can also enable or disable the whole domain. This is useful if you want to just disable it, but keep it in the system.
#### Authentication
SquadDNS allows you to **simply restrict access** to your tunnel, by enabling authentication options.
Authentication options automatically include both **BasicAuth** as well as the list of **allowed IP addresses**.
Basic Authentication users are automatically **all users in SquadDNS**. This includes administrators, users, but also guest accounts if you want to share your tunnel with someone.
The list of IP addresses considers the **global list** of the added IP addresses in the system.
{% hint style="info" %}
If the IP address is already recognized, no more Basic Authentication will be used for the visitor.
{% endhint %}
When you're done with your configuration, just click on **Update**.
You should now see an **Update indicator** in the top navigation, as well as next to your domain.\
The indicator will be automatically updated once the **system is ready** and new changes have been applied.
If you then refresh your page, you should see the updated list of domains.
{% hint style="success" %}
**Congratulations**, your domain should now succcessfully forward your request to the configured target endpoint!
{% endhint %}
## 3. Delete Domains
Domains can only be deleted by administrators.\
If you have that role, just click on delete and confirm your action.
Your domain should now be succesfully removed from the system.
{% hint style="warning" %}
Don't forget, that you also need to remove the domain in your DNS providers records, if you want to completely remove it from this world
{% endhint %}
# User Profile
The profile page allows users to adjust different kinds of information about the profile.
## Change Password
Just enter your new passwords and click on Save.
Once this is done, your new password will take effect on your new login attempt.
# System Settings
# App Domain
The main domain for SquadDNS is used as an **additional security layer**.\
You can set a domain and make sure that only requests through this domain are allowed for the administration.
Please note, to avoid that you lock yourself out, this can only be changed from the **config.yaml** file after the initial setup of the system.
# User Management
The user managenent gives you an overview of all available users in the system, along with options to create or even delete users.
## Purpose of users
Users are meant to be created for your team members, but also for individual guests.\
Every user will automatically be added to the **Basic Authentication** list, if turned on for domains.
This means if you restrict access to your personal tunnel, all users automatically have access to it.\
Please see the section **Roles** for more on **guest users**.
## Create Users
You can create new users for all your team members by simply setting a **username** and **password** for them. Passwords can of course be changed later on by the members in their [profile](/configuration/user-profile).
## Roles
Every user gets an additional role.\
Roles help to define the **privileges** of every member in your team.
Here is the list of available roles
### **Admin**
Administrators have full access to every part of the system. They can create domains and users, and also delete them.
### User
Users are members of your team. They only have access to modify domains such as adjusting the target, authentication settings and more. They cannot access system settings or delete anything.
### Guest
Guest users can be used to give external people access to your tunnel system.\
This is primarily used for the Basic Authentication feature.\
Guest users do not have access to the administration area.
## Delete User
You can simply delete a user by clicking on the Delete button and confirm it.\
You user is immediately removed from the system, and after a short restart of the system, also Basic Authentication options are automatically updated for you.
# Allowed IPs
Here you see a list of all allowed IP addresses.\
These addresses are automatically considered, if Authentication is turned ON for a domain.
SquadDNS will first check if the IP address is okay, if not it will use Basic Authentication as fallback.
## Create IP address
You can simply create a new entry by specifing your IP address along with an optional comment.\
The comment can be used to describe what the IP is about, or who the IP address is meant for.
After a short restart of the system, your new IP address is ready for your authentication options.
## Delete IP address
To delete an existing address, simply click on the button and confirm it.
# Receiving Webhooks
This is a simple tutorial, if you want to **receive webhooks from an external system**, such as from payment providers, ERP systen and more.
The tutorial is not bound to a specific software or programming language.\
It just requires any local web application running on your development machine.
## 1. Start Web App
Start your local we application.\
That's it, just do it, however it works for you (Docker, native, ...) and make sure its reachable with HTTP or HTTPS.
## 2. Start Tunnel
You can now decide what service you want to use for your tunnel.
{% tabs %}
{% tab title="NGROK" %}
We start by running our tunnel. In this case with NGROK.\
If you are not yet familiar with NGROK you might want to check it out here:
All we need is to run this line with port 443 (or 80 if you have http only) and with our hostname. This will make sure that our app thinks there is a request for this hostname, and not for the NGROK domain that would be used otherwise.
```bash
ngrok http --region=eu --host-header={my-hostname} 443
```
{% endtab %}
{% tab title="Cloudflare" %}
If you want to use the Cloudflare service, run the following command.\
This will start a tunnel that redirects to your HTTPS localhost. You can also use HTTP if you prefer that.\
\
It will also ensure sure that our app thinks there is a request for our static hostname, and not for the Cloudflare domain that would be used otherwise.
```
cloudflared tunnel --no-tls-verify --http-host-header={my-hostname} --url=https://localhost
```
{% endtab %}
{% endtabs %}
## 3. Update SquadDNS
The only thing that's left to do is, to copy the generated tunnel domain and add it to your record inside SquadDNS.
{% hint style="success" %}
That's it!\
You can now use your static domain in your webhook URL for your external system.\
If that system now calls the webhook, you should receive it locally.
{% endhint %}
# Shopware
# Shopware Remote Sharing
This is a simple tutorial, if you have a single Shopware shop, that you would love to share with someone else. The challenge is to configure Shopware in a way, that TWIG links will be rendered correctly, so that a full navigation is possible using the external static hostname.
## 1. Start Shopware
Start your local Shopware installation
Here is a simple Docker line using the dockware.io project to lunch Shopware 6.5.3.0 with Port 443 (HTTPS).
```bash
docker run -p 443:443 dockware/dev:6.5.3.0
```
## 2. Sales Channel Domain
We want our shop to render all links with the correct static hostname.\
Otherwise visitors would be redirected to when clicking somewhere, which does obviously only exist on the local machine, and not from remote.
This is why we have to add a new domain to our sales channel.\
Just use your personal static hostname and enter it in the administration of Shopware.
Pay attention to the HTTP(s) scheme, when doing this!
## 3. Start Tunnel
You can now decide what service you want to use for your tunnel.
{% tabs %}
{% tab title="NGROK" %}
Now it's time to start NGROK.\
If you are not yet familiar with NGROK you might want to check it out here:
All we need is to run this line with port 443 and with our hostname.\
This will make sure that our shop thinks there is a request for this hostname, and not for the NGROK domain that would be used otherwise.
```bash
ngrok http --region=eu --host-header={my-hostname} 443
```
{% endtab %}
{% tab title="Cloudflare" %}
If you want to use the Cloudflare service, run the following command.\
This will start a tunnel that redirects to your HTTPS localhost.\
It will also ensure sure that our shop thinks there is a request for our static hostname, and not for the Cloudflare domain that would be used otherwise.
```bash
cloudflared tunnel --no-tls-verify --http-host-header={my-hostname} --url=https://localhost
```
{% endtab %}
{% endtabs %}
## 4. Update SquadDNS
The only thing that's left to do is, to copy the generated tunnel domain and add it to your record inside SquadDNS.
{% hint style="success" %}
That's it!\
When you know open your static domain from a different machine, you should be able to see your Shopware shop, and also navigate to other pages.
{% endhint %}
# Shopware App System
Local development with external App system
If you are developing for and with Shopware, it can happen that you are using the App system.
The **worst case** is, that you develop a shop, that has a **third-party app** installed. And this app, or its backend-system, also **sends data to the shop**. If you are working locally, there's just **no chance** to make this work without things like tunnels.
It's indeed possible to just use a tunnel system without SquadDNS, but if you only get random domains, you also register **all kinds of random domains** in the system of the app manufacturer which leads to a lot of temporary and useless data.
It's technically okay, but let's be fair and avoid this, right?
This page shows you, how to setup your local Shopware to **register with your configured static hostname**, so that the external backend system can talk to your local Shopware API, if required.
## 1. Start Shopware
Start your local Shopware installation.
Here is a simple Docker line using the dockware.io project to lunch Shopware 6.5.3.0 with Port 443 (HTTPS).
```bash
docker run -p 443:443 dockware/dev:6.5.3.0
```
{% hint style="info" %}
Please keep in mind, there is a diffent tutorial availale for setups with multiple containers, services and reverse proxy options: [Shopware with Reverse Proxy](/tutorials/shopware/shopware-with-reverse-proxy)
{% endhint %}
## 2. Start Tunnel
{% tabs %}
{% tab title="NGROK" %}
If you use NGROK for your tunnels, please see the following sections.\
If you are not yet familiar with NGROK you might want to check it out here:
Now start NGROK with the corresponding port, such as HTTPS 443, as well as your static hostname. This one will make sure that all incoming requests are recognized as **{my-hostname}**.
```bash
ngrok http --region=eu --host-header={my-hostname} 443
```
{% endtab %}
{% tab title="Cloudflare" %}
If you use Cloudflare for your tunnels, please see the following sections.
OIf you just have a single Shopware container, you only need to start Cloudflare with the corresponding port, such as HTTPS, as well as your static hostname. This one will make sure that all incoming requests are recognized as **{my-hostname}**.
```bash
cloudflared tunnel --no-tls-verify --http-host-header={my-hostname} --url=https://localhost
```
{% endtab %}
{% endtabs %}
## 3. Shopware URL
The next thing is to configure our Shopware to use the correct static hostname when registering with the app.
This is usually used in an app backend system to **connect to Shopware** and its API.
The value that is used inside Shopware during the registration process comes from the **APP\_URL** in the **.env** file. (The sales channel domains don't need to be changed if you don't want to).
Make sure to adjut the .env file in the root folder of Shopware like this:
```bash
APP_URL={my-full-domain-with-https-schema}}
# samples
APP_URL=https://my-name-tunnel.my-company.io
```
## 4. Update SquadDNS
The only thing that's left to do is, to copy the generated tunnel domain and add it to your record inside SquadDNS.
{% hint style="success" %}
That's it!\
You can now install and activate the App in your local Shopware.\
It will register with the external backend system and make sure that this system can reach you using the provided static hostname and tunnel.
{% endhint %}
# Shopware with Reverse Proxy
Sometimes you have more than just a simple Shpoware instance in your development environment.\
In this case you usually use a **reverse proxy** that handles **routing** to your **local services**.\
And this requires more configuration for your tunnel setups inside the proxy to handle our domains.
But it can also be, that you need **webhooks for multiple services**. In this case you also need to make sure that the tunnel requests are routed correctly to the **correct target system**.
As you see, there are different use cases.
The good thing is that you can solve all of them, but you need a bit more knowledge on this of course.
This page helps you to dig deeper into **proxy configuration options**, so that you still end up with a nice **plug'n'play environment** for your developers.
## 1. Local Environment
Let's start with a sample environment based on Docker.
It contains a Shopware shop, an additional service (could be a Symfony application) and a reverse proxy based on NGINX.
The local development machine has 2 domains in /etc/hosts
* shop.local-domain.com
* symfony.local-domain.com
Once our developer opens these domains, the proxy (with port 80 and 443) is being called.\
Thanks to both bind-mounted configuration files, it will either forward the request to the Shopware shop, or to the Symfony application container.
{% tabs %}
{% tab title="docker-compose.yml" %}
```yaml
version: "3.0"
services:
proxy:
container_name: proxy
image: dockware/proxy:latest
ports:
- 80:80
- 443:443
depends_on:
- shop
- symfony
volumes:
- "shop.conf:/etc/nginx/conf.d/shop.conf"
- "symfony.conf:/etc/nginx/conf.d/symfony.conf"
shop:
container_name: shop
image: dockware/dev:6.5.3.1
symfony:
container_name: symfony
image: dockware/flex:latest
```
{% endtab %}
{% tab title="shop.conf" %}
```bash
server {
listen 80;
server_name shop.local-domain.com;
return 301 https://$host$uri$is_args$args;
}
server {
listen 443 ssl;
server_name shop.local-domain.com;
ssl_certificate /etc/nginx/ssl/selfsigned.crt;
ssl_certificate_key /etc/nginx/ssl/selfsigned.key;
location / {
proxy_pass https://shop;
}
}
```
{% endtab %}
{% tab title="symfony.conf" %}
```bash
server {
listen 80;
server_name symfony.local-domain.com;
return 301 https://$host$uri$is_args$args;
}
server {
listen 443 ssl;
server_name symfony.local-domain.com;
ssl_certificate /etc/nginx/ssl/selfsigned.crt;
ssl_certificate_key /etc/nginx/ssl/selfsigned.key;
location / {
proxy_pass https://symfony;
}
}
```
{% endtab %}
{% endtabs %}
## 2. Start Tunnel
{% tabs %}
{% tab title="NGROK" %}
If you use NGROK for your tunnels, please see the following sections.\
If you are not yet familiar with NGROK you might want to check it out here:
```bash
ngrok http --region=eu 443
```
{% endtab %}
{% tab title="Cloudflare" %}
If you use Cloudflare for your tunnels, please see the following sections.\
Once Cloudflare is installed, you can easily start it using this command.
```bash
cloudflared tunnel --no-tls-verify --url=https://localhost
```
{% endtab %}
{% endtabs %}
## 3. Tunnel NGINX Configuration
Let's create a new file **tunnels.conf** for our NGINX.
We have to adjust our **docker-compose.yml** and add it to the bind mounted files of the proxy (don't forget to restart the whole Docker containers at the end of this tutorial).
```bash
volumes:
....
- "tunnels.conf:/etc/nginx/conf.d/tunnels.conf"
...
```
The content of the tunnels.conf file (configuration below) makes sure that NGINX listens to both possible domain endings **ngrok-free.app** and **trycloudflare.com** (please adjust to your domains if you use something else).
If the proxy receives such a request, it will pass on the request to our containers.
If we receive a request starting with **/webhook**, the request is passed on to our Symfony application. But before we do this, the Host is being adjusted to **symfony.local-domain.com**.\
We only need to do this in case our Symfony application really listens to that incoming domain.\
Most simple PHP applications don't really care, and would just process the request.
Every other request is being passed on to Shopware.\
But why do we have the host set to **$HTTP\_SQUADDNS\_HOST**?\
This is another and dynamic way of setting our host. We decided on using our static domain for our Shopware. Because we only have 1 static domain, we don't have a separate one for Symfony of course, so we just set the Host to be the value that Symfony requires (in case it even does).
But for the shop, we can use the originally used domain from SquadDNS.
The actual **Host** variable in NGINX that is being received, is the NGROK or Cloudflare host, because the tunnels **overwrite** that entry. SquadDNS saves the original domain in a **separate header**, so you can use it if you need it, even though a tunnel service is in-between.
```bash
server {
listen 80;
server_name *.ngrok-free.app *.trycloudflare.com;
return 301 https://$host$uri$is_args$args;
}
server {
listen 443 ssl;
server_name *.ngrok-free.app *.trycloudflare.com;
ssl_certificate /etc/nginx/ssl/selfsigned.crt;
ssl_certificate_key /etc/nginx/ssl/selfsigned.key;
location /webhook {
proxy_set_header Host symfony-local-domain.com; # might be optional
proxy_pass https://symfony;
}
location / {
proxy_set_header Host $HTTP_SQUADDNS_HOST; # required by Shopware Sales Channel domain recognition
proxy_pass https://shop;
}
}
```
{% hint style="info" %}
**Attention**, you can already set the **header** you want to be used when **starting the tunnel**.\
\
\>> ngrok http --host-header={my-hostname} 443 (also works for Cloudflare).\
\
In this case all requests will be received from our proxy, **already with this server name**.\
So instead of listening to the \* ngrok and cloudflare domains, you can already **listen** to your static domain in NGINX.
It's up to you to decide what way to go. While starting the tunnel already with the correct host gives an **easier flow**, the other approach helps to **centralize the "magic"** within the NGINX configuration file only.
{% endhint %}
{% hint style="warning" %}
**Don't forget.** If you really want to use the Shopware shop from remote in the **browser**, you might also need to adjust the **sales channel domains** to match your static domain!
{% endhint %}
## 4. Update SquadDNS
The only thing that's left to do is, to copy the generated tunnel domain and add it to your record inside SquadDNS.
{% hint style="success" %}
That's it!\
You can now use your static domain for both the Symfony application (/webhook) as well as the Shop system.
{% endhint %}
# Shopware Domain-Switch Automation
If you want to allow a remote user to browser your local shop, you need to make sure that the sales channel domain of your Shopware match the static hostname you are using.
Why? Simply because links on the shop are being rendered through TWIG by using the configured sales channel domain and not the domain being currently used.
If you don't pay attention, you might see the first page working, but as soon as you click somewhere it would redirect to the local development host (or localhost), which does obviously not work from remote.
You can either adjust the domains **manually**, or use this **automation option**.
```bash
php bin/console sales-channel:update:domain --previous-domain=dev-local.domain.com $(DEV_TUNNEL_DOMAIN)'
php bin/console cache:clear'
bash -c "trap 'php bin/console sales-channel:update:domain --previous-domain=$(DEV_TUNNEL_DOMAIN) dev-local.domain.com' EXIT; ngrok http 443"
```
This script starts by switching from the local development domain, to the static domain that you use. (you need to adjust it to your needs of course).
Afterwards it clears the cache.
The last command is already the most important on.\
It basically only starts NGROK (adjust this to your needs). \
But instead of just starting the tunnel, it uses a **trap** for it.
A trap allows you to listen to the event when the command is being **stopped** or an **exit** happens.\
Because tunnel services are synchronous calls, they will just open and stop while running.
As soon as the tunnel is stopped (e.g. CTRL+C), **the trap executes** the other provided command, which automatically **reverts** our **sales channel domain** back to the **original** local development domain.
With this plug'n'play approach, a developer can just go back from local to tunnel and back to local without anything to take care of.
