Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Nginx for Human-Friendly URL (Confluence)

Hello, Community!

Having spent a couple of days trying to get NGINX and Confluence work together as expected I decided to share my experience with you. 

We want to use our Confluence as a public website so we have some SEO considerations such as human-friendly URLs. Yes, I know that there is guidance for making clear URLs without "?pageId"-thing but, unfortunately, this is not our case as we don't use English for our website.

In the config example below there's also a "proxy_pass" section. We use NGINX also as a reverse proxy to change the default port 8090 to standard 80 (as described here)

So, here we go:

server {
location / {
client_max_body_size 100m;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
root /opt/atl/instd/atlassian-confluence-6.8.2/confluence/;
location /pages {
if ($args ~ pageId=xxxxxx) {return 301 /your-pretty-url1-goes-here;}
if ($args ~ pageId=yyyyyy) {return 301 /your-pretty-url2-goes-here;}
rewrite ^/your\-pretty\-url1\-goes\-here?$ /pages/viewpage.action?pageId=xxxxxx break;
rewrite ^/your\-pretty\-url2\-goes\-here?$ /pages/viewpage.action?pageId=yyyyyy break;
proxy_pass http://localhost:8090/;
location /synchrony {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8091/synchrony;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";

Let me explain what do we have here:


root /opt/atl/instd/atlassian-confluence-6.8.2/confluence/;

changes the root for nginx so that it looks for pages from there. The default "/usr/share/nginx/html/" results in "failed (2: No such file or directory)".


 location /pages {

I choose "/pages" as a nested location, because all of our anonymously accessed pages URLs look something like:


if ($args ~ pageId=xxxxxx) {return 301 /your-pretty-url1-goes-here;}

 redirects the request with the particular pageId to your custom URL

4. And, finally

rewrite ^/your\-pretty\-url1\-goes\-here?$ /pages/viewpage.action?pageId=xxxxxx break;

  rewrites back to the original source page.

The main advantage for us here is that pages diplayed with normal, human-readible URLs all the time whether it's an external link with friendly URL already in place ( or an internal Confluence link. All of them are displayed correctly.

There are also some drawbacks, of course.

The first one is that you have to manually edit the nginx config file for every new page you create. In our case it's not so awful as our website is going to be static.

The second one is that I don't really know how search engines would react to such 301 redirects of ours and wouldn't it be SEO-unfriendly.

So, that all for now. If someone notices any mistakes or has any suggestions, you are most warmly welcome to the discussion :)

Thank you for your attention.

1 comment

Hi Greg! 


I have been asked my users the same questions, unfortunately, we just stop use hard solution. 

But I have used rewritemap directive from httpd. (in the nginx it likes map)


Anyway, if I were you I have do it, external map file:

1. then include it into configuration, which will located on NFS server(then editor can edit map file which mounted on the PC) like this

2. every 1 minute bash script will check  command :

nginx -t 

if it gets config is ok, the run

systemctl reload nginx 


Regarding SEO, I hope this article will help

In my experience, I have used for the SEO trick rewrite rules, if it is not good start user redirect with 301 error.


Hope it helps.




Gonchik Tsymzhitov



Log in or Sign up to comment
Community showcase
Published in Confluence

Confluence: Where work and wellness meet

Feeling overwhelmed by the demands of work and life? With a 25% increase in the prevalence of anxiety and depression worldwide during the pandemic, for most of us, it’s a resounding yes . 🙋‍♀️ ...

768 views 5 21
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you