[Feature] Support base url on the web app

[usikpavel]

Describe the bug
Immich server is deployed using default docker-compose.yml on the private host (Windows10) at http://192.168.3.3:2283/
It is accessible via reverse proxy (Windows Server 2019, IIS 10) at public url http://pavelusik.ru/photosImmich/

Main page is loaded successfully, but is not working. The reason is that /_app/immutable/start-a8372751.js file relative path is wrong:

    import { start } from "/_app/immutable/start-a8372751.js";

and therefore error 404 occured.
All other files (css, js, json, favicon, etc) are loaded successfully by their correct relative addresses /photosImmich/...path...

Task List

• I have read thoroughly the README setup and installation instructions.
• I have included my docker-compose file.
• I have included my redacted .env file.
• I have included information on my machine, and environment.

To Reproduce
Steps to reproduce the behavior:

1. In browser, open developers console, Network tab
2. Go to http://pavelusik.ru/photosImmich/
3. See downloaded files and errors

Expected behavior

• All files are downloaded by its relative paths /photosImmich/...path...
• All links are correct too.

System

• Server Version: v1.25.0_35-dev on Windows 10 running in docker
• Public reverse proxy server: Windows Server 2019, IIS 10 (with modules URL Rewrite 2, Application Request Routing 3.0)

Additional context
docker-compose and env.zip

[alextran1502]

I think the problem here is that you have /photosImmich append to the URL. So you will need to proxy or rewrite any /api to http://192.168.3.3:2283/api If you use your domain as photoImmich.pavelusik.ru it should work

[usikpavel]

Do you mean that Immich-web can run only in root path?

Another files are downloaded properly.
Mobile app (Android) works correctly (/photosImmich/api path is ok).

The problem is only in Web-app, and is related only to /_app/immutable/start-a8372751.js file. When opening another page manually auth/login, there is the same error. Login request works correctly, but loaded page has the same error.

[ioogithub]

hey @usikpavel you mention that you were able to get the mobile app /photosImmich/api working correctly?

Can you share what proxy rewrite rules you used to accomplish this? I am using apache however if I know what URLs to redirect I can translate from your IIS config.

I have tried something like this:

ProxyPass "/immich/api" "http://localhost:2283/api"
ProxyPassReverse "/immich/api" "http://localhost:2283/api"

but it doesn't work. I get an TLS/SSL communcation failed: POST /oath/config error

[zhuyuhui97]

Exactly. The API works fine with url rewrite, at least I didn't see any HTTP error from nginx reverse proxy while using the iOS app.

The webapp keeps pulling assets from fixed url regardless the base url.

[alextran1502]

I might have the wrong assumptions.

I think what you do is fine, it seems the proxy is working fine as well. I am not sure why that file isn't loaded correctly. Let me do some digging.

At the mean time, can you try to pull immich-web container again and start it backup?

[usikpavel]

All containers are up-to-date:

>docker-compose pull
Pulling immich-web              ... done
Pulling redis                   ... done
Pulling database                ... done
Pulling immich-machine-learning ... done
Pulling immich-microservices    ... done
Pulling immich-server           ... done
Pulling immich-proxy            ... done

> docker-compose up -d
immich_redis is up-to-date
immich_postgres is up-to-date
immich_immich-web_1 is up-to-date
immich_immich-server_1 is up-to-date
immich_immich-machine-learning_1 is up-to-date
immich_immich-microservices_1 is up-to-date
immich_proxy is up-to-date

[panoti]

@usikpavel Immich web can not work perfectly with path prefix now because of web framework config. You'd better use mobile only if you still wanna use path prefix, or use subdomain instead. I hope immich team will fix support it soon.

@alextran1502 I have a small test with web, Svelte kit not support base url perfectly because goto function not use base url in default. If we support base url, we have to pass base url to all goto function, IMO.

[nando2301]

I have problem using HAProxy as SSL termination using something like https://domain.com/immich

I added ACL to manage /immich and /fonts/*** but does not work.

[Thrilleratplay]

Wanting run Immich under a path using a duckdns address, I am running into this issue as well. I believe this is the related Svelte issue

[maoe]

I ran into this issue when I tried to publish Immich using Tailscale Funnel, which currently doesn't support subdomains. It'd be great if Immich could support this.

[balu-]

I ran into the same issue and would like it if it was possible to run immich under a subpath

[ioogithub]

I need to use a baseurl this is really the only choice I have but luckily every single other app I want to host has supported this. I thought it was a pretty basic feature after all every app can't take the root of the server. Is it true that immich cannot do this:

http://server:port/immich

I will not be able to use immich until this is supported. Can anyone confirm that immich does not support base url and that there are no plans to support it in the futture before I invest more time into looking for a solution.

[alextran1502]

@ioogithub yes that is correct that we are not supporting sub path

[alextran1502]

Please feel free to look into a solution, we will be happy to integrate if it works

[ioogithub]

Thanks for confirming. It sounds like @usikpavel as the mobile working with the /api url. The documentation just mentions to use the mobile app you need to use this url: http://:2283/api. Does this page redirect to something else such as http://:2283/oath/config? I am trying to add proxy rewrite rules to add a base url like this: https://domain.com:2283/immich/api but nothing is working.

If I can get just the mobile working that would likely be good enough for now but without further documentation on how this /api URL works its difficult.

[HybridSarcasm]

http://server:port/immich

This is exactly what I need, as well. Been trying all kinds of Traefik tricks, but it would seem the config needs to be set a a lower layer. Hoping someone has figured that out.

[alextran1502]

Jason actually one of the main maintainer of the project. We invoke questions to help articulate thoughts and answers, if you find that offensive, that would be unfortunate.

As of right now, we don't support subpath, only subdomain and we are not planning to support subpath

[HybridSarcasm]

@ctp-tCG You’re being rather rude in this thread. The maintainers of this project don’t work for you. They are beholden to you in no way. You are free to implement the feature you want in a Pull Request. Otherwise, respect the people who put in the massive amount of work to create and maintain a project like this.

[jrasm91]

FWIW - we have already looked into supporting subpath (and would like to in the future), but the web framework we use does not support it out of the box so it is quite complicated and involved to get it working at the moment. Since a subdomain works just fine for just about everyone that is the current recommend way to use it with a domain.

If you cannot or are unwilling to use a subdomain, feel free to look elsewhere. The discussion will be updated when/if subpath is supported.

[alextran1502]

Alright, that is it

[HybridSarcasm]

Jason actually one of the main maintainer of the project. We invoke questions to help articulate thoughts and answers, if you find that offensive, that would be unfortunate.

As of right now, we don't support subpath, only subdomain and we are not planning to support subpath

What a measured and mature response. It’s refreshing from developers, certainly devs working for free. You just made a fan for life!

[Thrilleratplay]

Not to lessen how well that was handled, I want to highlight that sometimes the harsher comments developers and maintainers of open source projects should be taken with a grain of salt. Many open source projects are a labor of love, made to fulfill a personal need or scratch an itch and share what they made with others to who may have a similar need. These devs are often have families, careers and other stressors that consume a majority of their time. With the little time they can devote to their projects that share, if it is meet with entitled demands, arguments and sass over and over, I can forgive the dev for being short or even crass in a reply. I do not know what else they are dealing with in their lives, I do not know if there is a language or cultural barrier where flat text has a different tone than intended, and I do not know if they will try to correct it when cooler heads prevail.

There are devs who are known for being jerks and be so adversarial to their communities that the project is forked (FreeRSS comes to mind). If a user disagrees with those in charge of an open source project, they usually have the right to fork the project to fit their own needs. What they do not have the right to do is demand or bark orders to those who have donated their time. Burn out a very high in open source projects because of situations like this. Again, if you disagree, fork the project and create a pull request or just do it on your own. This is a feature I want as well however, I do not have the time to commit to it given my other obligations.

My apologies for this rant and know it is off topic. Please feel free to mark it as such, I wanted to highlight that we all try to be both measured and mature in our responses, there can be more to a response than just the words that are contained with in it.

[einarpersson]

Is this still not supported by Sveltekit? I am in the same boat (trying to setup Immich+Caddy behind tailscale) and just cannot get it to work.

The docs seem to imply that it is doable, but maybe I am misreading? (see also sveltejs/kit#595)

Would appreciate if you could take another look at this, beacuse I am kinda stuck. ❤️

[gardiol]

Adding my 2 cents here. This feature would be very useful to lots of people, including me i guess. I cannot (don't know how) add this myself, so i hope somebody can chime in.

[bobledeveloppeur]

Hi,
If the framework cannot use relative urls, would it be possible to change all paths in a "immich" directory ?
That is not sexy but open doors for new reverse proxy rules.

[ahmedelq]

I'm running Immich on the LAN, hence I can't create a subdomain. an environment variable such as IMMICH_BASE_PATH would be a nice solution to solve this.

[mmomjian]

If you are running it on the LAN, is there a reason you can't run Immich on a different port and access it by the root?

[ahmedelq]

I'm casing all of my services behind a reverse proxy (nginx) and using a single SSL certificate.

I wish there's something similar to Quartz's configuration. It's really smooth, it provides baseUrl to make the deployment path agnostic. I wonder if we can have something similar.

[mmomjian]

@ahmedelq why can’t you create a subdomain on LAN? All you need to do is get a wildcard SSL cert (which you can do even for a self signed cert) and add a DNS entry. For example, let’s say your server DNS is server.internal. You can generate a cert for *.server.internal, add a DNS entry for Immich.server.internal, and then add an entry in nginx using the servername directive to proxy it to Immich.

[troyliu0105]

I think it will provide better security when you use subpath with ssl.
Since hackers only know domain.

[mmomjian]

Hackers won't know the domain either if you use a wildcard cert. Even if the domain was known, this is a very poor example of security through obscurity.

[aveexy]

I've created an nginx config for those who need this to work now:
https://gist.github.com/aveexy/4b2b22b2198636b0a91c7c142ec11b37

But this is no long term solution of course, it would be great if immich would support this out of the box. It shouldn't be that hard to implement because Sveltekit already supports base urls, in fact the nginx config rewrites the Sveltekit config and sets the base path.

[jrasm91]

Feel free to open a PR to implement the feature 👍

[benjamonnguyen]

it is much cleaner to have the reverse proxy handle stripping path prefix before routing requests to a server considering how common this requirement is. This allows upstream servers to remain unaware that they are being reverse proxied, rather than requiring code changes

[aveexy]

But then it might be necessary to change the reverse proxy server config for each app update.

[gardiol]

No other apps does it this way.
The industry standard approach (stuff like gitea, Gerrit, WordPress, jellyfin, the 'Arts, Podfetch, etc etc...) Is to have a setting in the app itself, not in the reverse proxy.

The reverse proxy approach is always a workaround when the app is reticent to support it.

Don't get me wrong.... Do it anyway it's best for Immich, its just kind of expected and preferred to have it the way everybody else does.

[aveexy]

To properly support reverse proxies that change the base url we could implement the X-Forwarded-Prefix header. It's non standard but there's already software out there (aspnet, traefik, apache flask) that support it.

[gardiol]

It works! Maybe it can be added to the immich documentation while waiting for the discussion to reach a consensus?

[alextran1502]

We'd like to support it, however it is not on the priority list. So we leave this open for the community's contribution

[gardiol]

Iwas referring to add the nginx setup to immich docs

[HazelCuate]

Does X-Forwarded-Prefix work with the mobile app?

[aveexy]

The mobile app already works with base urls (atleast on ios, have not tried android yet)

[Enzo-Kerkhof]

Hi, I'm using ngin reverse proxy manager with already a home assistant instance using my root path + a specific custom location aka subpath config for a overseerr instance pointing to domain/overseerr.
This is all specific so I cannot seem to make the nginx config file above work.

I'd love to see this base url feature make it at some point!
In my situation I have a free domain from my ISP to my fixed external IP, which is nice to use. Though I cannot add subdomains. So to just rent a domain name just for this....

[OverHash]

My use case was highlighted earlier on in this post, but I will reverberate it for clarity:

Using tailscale funnel is a convenient way for me to expose my Immich server to the internet. However, you have no control over the domain part (node-name.tailnet-name.ts.net). That is, you cannot create a subdomain.

This forces you to use path qualifiers (such as node-name.tailnet-name.ts.net/immich/), or other solutions. Currently, Immich does not support this (for me to be able to configure Immich to say to the server to serve content at /immich).

[OverHash]

Having a quick look at the relevant code when creating the server, this feature might be a matter of simply patching this code to be base-path aware.

Calling app.setGlobalPrefix("api") makes the Nest app expect a base path of /api, so we could leverage this to prefix with our own base path:

app.setGlobalPrefix(`${customBasePath + '/'}api`, { exclude: excludePaths });

and then it is a matter of patching the other paths served.

The main problem might be sirv, which I can't see a good way of rerouting requests (see lukeed/sirv#148)

---

The more trivial solution might be just to create a Nest middleware to rewrite responses.

[zhuyuhui97]

Hi all,

I’ve come up with a workaround to host Immich with a predefined prefix. I am not an expert in web developing, so please feel free to point out mistakes if there's any! ;)

TL;DR

The core idea is to ensure that "routing actions" are handled by SvelteKit, which appends the base path to internal URLs. The solution requires YOU pre-defining the prefix, compiling the code, and hosting the web app on an external HTTP server. The modified web app runs alongside the official Docker image, and these two parts are put together by an Nginx server.

Steps:

1. Fix the base path of OpenAPI SDK and all redirections involving routing, which is basically appending the {base} string to internal URLs. Check out the changes in my fork. (moved to branch base_url)
2. Modify the SvelteKit configuration in web/svelte.config.js to set the base path:

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    paths: {
      base: '/immich',
    },
  },
};

3. Compile the web app and deploy the generated files from web/build to the server path $NGINX_HTML_ROOT/immich.
4. Configure an Nginx server to serve static files and proxy API requests to the backend:

location /immich/ {
  root /usr/share/nginx/html/;
  try_files $uri /immich/index.html;

  location ~ /immich/api(.*) {
    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_buffering off;

    proxy_pass http://immich_server:3001;
    rewrite /immich/(.*) /$1 break;

    # Reverse proxy settings from Immich
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_redirect off;

    # Timeout settings
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    send_timeout 600s;
  }
}

However I couldn’t find a good solution for a dynamic prefix (i.e., one defined before compiling or generated on the fly). There are too many restrictions in the Immich codebase and the SvelteKit framework.

I also found a potential solution if we can make some further adjustments, but it may conflict with the maintainers’ intent. I’m happy to share if anyone is interested! :)

Web App Side

Static Assets:

Immich is built as a client-side rendered single-page app (SPA), and SvelteKit won’t generate relative links for SPAs, which affects the URLs for static assets.

From the SvelteKit documentation:

Single-page app fallback pages will always use absolute paths, regardless of this setting.

According to discussions from other SvelteKit projects, partly rendering the file at the server side could help. However, since the Immich web app is built as a static file bundle, the best we can do is define the base URL before compiling.

Relevant issues of SvelteKit: #595, #9569, and #10235

OpenAPI Base URL:

API URLs are defined in the OpenAPI SDK with the base URL specified in the same file:

immich/open-api/immich-openapi-specs.json

Lines 7401 to 7405 in aa0097b

	"servers": [
	{
	"url": "/api"
	}
	],

Since exported methods rely on this base URL, you can either define the value before compiling, or set it dynamically in hooks.*.ts when the page is loaded.

The latter approach avoids modifying the OpenAPI configuration and IMO is more suitable for a dynamic base URL (if that becomes possible in the future).

URL Routing:

This is the tricky part. The routing paths are defined by the AppRoute constant:

immich/web/src/lib/constants.ts

Lines 14 to 51 in aa0097b

	export enum AppRoute {
	ADMIN_USER_MANAGEMENT = '/admin/user-management',
	ADMIN_LIBRARY_MANAGEMENT = '/admin/library-management',
	ADMIN_SETTINGS = '/admin/system-settings',
	ADMIN_STATS = '/admin/server-status',
	ADMIN_JOBS = '/admin/jobs-status',
	ADMIN_REPAIR = '/admin/repair',
	ALBUMS = '/albums',
	LIBRARIES = '/libraries',
	ARCHIVE = '/archive',
	FAVORITES = '/favorites',
	PEOPLE = '/people',
	PLACES = '/places',
	PHOTOS = '/photos',
	EXPLORE = '/explore',
	SHARE = '/share',
	SHARING = '/sharing',
	SHARED_LINKS = '/sharing/sharedlinks',
	SEARCH = '/search',
	MAP = '/map',
	USER_SETTINGS = '/user-settings',
	MEMORY = '/memory',
	TRASH = '/trash',
	PARTNERS = '/partners',
	BUY = '/buy',
	AUTH_LOGIN = '/auth/login',
	AUTH_REGISTER = '/auth/register',
	AUTH_CHANGE_PASSWORD = '/auth/change-password',
	AUTH_ONBOARDING = '/auth/onboarding',
	UTILITIES = '/utilities',
	DUPLICATES = '/utilities/duplicates',
	FOLDERS = '/folders',
	TAGS = '/tags',
	}

These route links are used in these 3 actions but none of them handle the {base} variable:

• 301 redirect:

  immich/web/src/routes/admin/+page.ts

  Line 6 in aa0097b

  redirect(302, AppRoute.ADMIN_USER_MANAGEMENT);

• goto():

  immich/web/src/routes/auth/login/+page.svelte

  Lines 19 to 23 in aa0097b

  	<LoginForm
  	onSuccess={async () => await goto(AppRoute.PHOTOS, { invalidateAll: true })}
  	onFirstLogin={async () => await goto(AppRoute.AUTH_CHANGE_PASSWORD)}
  	onOnboarding={async () => await goto(AppRoute.AUTH_ONBOARDING)}
  	/>

• <a href>:

  immich/web/src/lib/components/shared-components/navigation-bar/account-info-panel.svelte

  Lines 77 to 83 in aa0097b

  	href={AppRoute.USER_SETTINGS}
  	on:click={() => dispatch('close')}
  	color="dark-gray"
  	size="sm"
  	shadow={false}
  	border
  	>

The side-bar-link component uses resolveRoute() to map the source code path to the runtime route:

immich/web/src/lib/components/shared-components/side-bar/side-bar-link.svelte

Line 16 in aa0097b

$: routePath = resolveRoute(routeId, {});

This function handles the {base} variable by default, which looks pretty nice, and I’ve updated all internal links to use it. IMHO resolveRoute() is the best mechanism for resolving routes. Using it universally would improve portability and internal link handling. I STRONGLY RECOMMEND using this globally.

Server Side

There are nothing to do with the server since the nginx can handle the proxying very well at this moment. What we have to do is just fix some bugs that caused by the transparent proxying. For example, the logout API returns a hard-coded 302 which won't integrate with the client-side URL:

immich/server/src/services/auth.service.spec.ts

Lines 183 to 221 in aa0097b

	describe('logout', () => {
	it('should return the end session endpoint', async () => {
	systemMock.get.mockResolvedValue(systemConfigStub.enabled);
	const auth = { user: { id: '123' } } as AuthDto;
	await expect(sut.logout(auth, AuthType.OAUTH)).resolves.toEqual({
	successful: true,
	redirectUri: 'http://end-session-endpoint',
	});
	});
	it('should return the default redirect', async () => {
	const auth = { user: { id: '123' } } as AuthDto;
	await expect(sut.logout(auth, AuthType.PASSWORD)).resolves.toEqual({
	successful: true,
	redirectUri: '/auth/login?autoLaunch=0',
	});
	});
	it('should delete the access token', async () => {
	const auth = { user: { id: '123' }, session: { id: 'token123' } } as AuthDto;
	await expect(sut.logout(auth, AuthType.PASSWORD)).resolves.toEqual({
	successful: true,
	redirectUri: '/auth/login?autoLaunch=0',
	});
	expect(sessionMock.delete).toHaveBeenCalledWith('token123');
	});
	it('should return the default redirect if auth type is OAUTH but oauth is not enabled', async () => {
	const auth = { user: { id: '123' } } as AuthDto;
	await expect(sut.logout(auth, AuthType.OAUTH)).resolves.toEqual({
	successful: true,
	redirectUri: '/auth/login?autoLaunch=0',
	});
	});
	});

[Shihira]

非常好贡献！我这边尝试了一下你的fork（不过是手工merge的，因为我服务端代码比较新），发现resolveRoute或许不需要加到所有地方佢，可能只需要把constants.ts中的绝对路径改为类似于./admin/user-management的相对路径，然后在app.html中加一个<base>标签。

Great contribution! I tried your commits on my build, and found that resolveRoute may not need to be added everywhere. It might only be necessary to change the absolute paths in constants.ts to relative paths like ./admin/user-management, and then add a <base> tag in app.html.