The usage of BASE_URL and VIRTUAL_HOST

Hello everyone,

After some investigating, I have some pieces of information about the current usage of BASE_URL, VIRTUAL_HOST and the communication between services in the core project.


VIRTUAL_HOST - the main usage this env variable is the name of the nginx server as it is described in the settings env file:
The virtual host for the nginx server - nginx will make services available under this host.

nginx consul template

The second usage of this variable is to set the server host for the scalyr.

scalyr config

This variable is set in:

  1. .env file of each service
  2. In the script to localhost

BASE_URL - the env variable which is used in the generated links pointing to the olmis distribution and the communication between services. I will describe each usage separately:

Generated links - the base_url is directly used in the classes itself to generate links for the email notifications or it is assigned to the value in the application properties: notification.url

application properties

Getting BASE_URL by getEnv java method

Communication between services -







In each service, I have found some of those variables in the which are used to perform the HTTP request to other services.

The communication in the core project.

We can assume that if the service wants to perform any request to the other service, it communicates with the nginx container and gets the correct address for the required container (as part of the service discovery). This image also says that the performed request is in the same docker network for all of the processes.

Later I will describe another look at this.

The communication in the Angola project.

Everything is well described in the link above by Wojtek but I would like to take a note on one comment: Let's Encrypt SSL/TLS for OpenLMIS - #5 by wbulawa

We have needed to change the BASE_URL address to pointing DIRECTLY to the nginx container (nginx-reverse-proxy) which is inside the inner network of this setup. The core usage of BASE_URL here (the same value as virtual host with HTTP) was not successful and ends with SSL issues and not traffic at all.

Why the BASE_URL can’t be used in the Angola Let’s Encrypt Solution in the same way as in the core?

I have done some testing and networking traffic logging for the core project and from my understanding the current communication workflow is a bit different than the image shows. If the BASE_URL is set to be the same as the VIRTUAL HOST env variable, the container makes a request to the docker host address which does directly point to the nginx container (because it is mapped to port: 80) but it has to make a way thought the docker host bridge which may looks like this:

With this in mind, the nginx TLS container in the Angola Let’s Encrypt setup gets the request and reject it because of lacking https or public keys.

This is possibly the reason why we can’t leave the BASE_URL to be the same as VIRTUAL HOST because we don’t want to reach the TLS nginx container but just the inner nginx container to perform service discovery stuff.

I have set the BASE_URL to http://nginx in the core project to directly point to the nginx container by the compose service name and everything works the same as before except the generated links for the users.


With keeping in mind all of the above, the Angola team would like to add a completely new env variable to the core project for links generated for notifications, which would be named e.g. BASE_HOST_URL and it would be an optional variable. In case when the BASE_HOST_URL is not set, the BASE_URL would be used.

This change would require to replace all occurrences of BASE_URL in case of notifications usage and won’t destroy anything in the core project because we left the BASE_URL unchanged. It would help the Angola Team to apply the Let’s Encrypt solution with working generated links. Also, we would like to do those changes before the incoming release.

Also, I think that the case of docker traffic networking and how the communication between services works in the core can be left for later discussion or the next technical committee.

What do you think?


Thank you @mwedel for this great write-up.

I think what you’re saying is that in a more ideal state we have environment variables for three things:

  • The public host (i.e. what’s in the HTTP header)
  • The public URL, including protocol and port
  • The “internal” address for the reverse proxy

What you’re proposing is a stop-gap which adds a new variable for notification links (BASE_HOST_URL), and an in-depth update to the Notifications service. Right?

Thank you @joshzamor

Exactly, that’s what I meant by my post.

That’s right, the proposal is to add a new variable for the links.

The list of services where we would need to do an update to the new variable:

  • Notification (as for email confirmation generated link)
  • Requisition (as for requisition URL (here and here and here) in the notifications)
  • Stock management (as for two generated links)
  • Auth (as for Password Reset url)
  • Fulfillment (as for PoD link)

because in each place the BASE_URL variable is taken from the environment. As I mentioned, the BASE_HOST_URL would be an optional variable and the BASE_URL would be used if the BASE_HOST_URL wouldn’t be set. With this in mind, the notification service will not change much. Rather, it is the small update to a few services.


If we have to touch most of the services, why don’t we go all the way to our ideal state, instead of the stop-gap?

Because the change that Mateusz is proposing for now is low-risk and small enough to fit in the upcoming release. It also won’t affect anyone as the new env variable is optional (if not provided, the BASE_URL is used).

Josh, do you have any specific concerns about this smaller change for now? If so, that’s fine - just let us know, so we can drop this idea and focus on looking for a workaround on Angola side.


Per technical committee we have agreed to go with the less risky option of additional (optional) variable. The feedback is that the naming of this variable could be improved so that it more clearly represents its value, and so the proposal was “PUBLIC_URL”. Of course the READMEs must be updated to explain how this variable behaves and what is it used for. If you are fine with that naming @mwedel then this can be implemented to satisfy Angola needs. If you have better ideas for its name, let us know.


Thanks @Sebastian_Brudzinski and @joshzamor

The “PUBLIC_URL” sounds great and I think it can be used. I will create the ticket for implementation.