Environment Variables for initial user-creation

deekerman commented

2026-02-28 03:12:53 -05:00

Owner

Originally created by @Twinki14 on GitHub (Dec 25, 2023).

⚠️ Please verify that this feature request has NOT been suggested before.

I checked and didn't find similar feature request

🏷️ Feature Request Type

API, Other

🔖 Feature description

Uptime Kuma is currently next-to-impossible to declaratively configure and manage, this makes it especially hard to host in volatile environments like Kubernetes or even a volatile docker environment where data may not be persisted intentionally.

✔️ Solution

Two environment variables would allow for initial user creation, which would open the doorway to third-party tools like uptime-kuma-api to declaratively configure Uptime Kuma whenever Uptime Kuma is initially deployed without needing any user interaction

UPTIME_KUMA_USERNAME for setting the initial username
UPTIME_KUMA_PASSWORD for setting the initial password

When both environment variables are present, and pass any other validation, a user could be created for tools like uptime-kuma-api to begin 'seeding' Uptime Kuma without any needed user interaction

❓ Alternatives

This is possible without environment variables, by opening the sqlite db and adding a user/password directly to the user table through , but this is quite a hacky workaround that could be officially simplified

📝 Additional Context

I wanted to use Uptime Kuma for my kubernetes cluster, it looks and appears quite supported, but since setting up Uptime Kuma absolutely requires user interaction inside a browser, it completely goes against my kubernetes cluster design.

Originally created by @Twinki14 on GitHub (Dec 25, 2023). ### ⚠️ Please verify that this feature request has NOT been suggested before. - [X] I checked and didn't find similar feature request ### 🏷️ Feature Request Type API, Other ### 🔖 Feature description Uptime Kuma is currently next-to-impossible to declaratively configure and manage, this makes it especially hard to host in volatile environments like Kubernetes or even a volatile docker environment where data may not be persisted intentionally. ### ✔️ Solution Two environment variables would allow for initial user creation, which would [open the doorway to third-party tools like uptime-kuma-api](https://github.com/lucasheld/uptime-kuma-api) to declaratively configure Uptime Kuma whenever Uptime Kuma is initially deployed without needing any user interaction - `UPTIME_KUMA_USERNAME` for setting the initial username - `UPTIME_KUMA_PASSWORD` for setting the initial password When both environment variables are present, and pass any other validation, a user could be created for [tools like uptime-kuma-api](https://github.com/lucasheld/uptime-kuma-api) to begin 'seeding' Uptime Kuma without any needed user interaction ### ❓ Alternatives This is possible without environment variables, by opening the sqlite db and adding a user/password directly to the user table through , but this is quite a hacky workaround that could be officially simplified ### 📝 Additional Context I wanted to use Uptime Kuma for my kubernetes cluster, it looks and appears quite supported, but since setting up Uptime Kuma absolutely requires user interaction inside a browser, it completely goes against my kubernetes cluster design.

deekerman added the

feature-request

A:deployment

A:core

labels

2026-02-28 03:12:53 -05:00

deekerman commented

2026-02-28 03:12:56 -05:00

Author

Owner

@CommanderStorm commented on GitHub (Dec 25, 2023):

Also see

current status on IAC: https://github.com/louislam/uptime-kuma/issues/3578#issuecomment-1751696927
api: https://github.com/louislam/uptime-kuma/pull/3854

@CommanderStorm commented on GitHub (Dec 25, 2023): Related https://github.com/louislam/uptime-kuma/issues/956 https://github.com/louislam/uptime-kuma/issues/1354 Also see - current status on IAC: https://github.com/louislam/uptime-kuma/issues/3578#issuecomment-1751696927 - api: https://github.com/louislam/uptime-kuma/pull/3854

deekerman commented

2026-02-28 03:12:56 -05:00

Author

Owner

@jsnouffer commented on GitHub (Jan 3, 2024):

I am disappointed that this minimal feature of configuring credentials via env var is not supported. The strong stance against config files make this impossible to deploy via GitOps. I was going to go the route of using the API to add endpoints, but without being able to bootstrap the service with user credentials, manual action is still required.

I love the kuma UI, but I'm forced to use gatus.

@jsnouffer commented on GitHub (Jan 3, 2024): I am disappointed that this minimal feature of configuring credentials via env var is not supported. The strong stance against config files make this impossible to deploy via GitOps. I was going to go the route of using the API to add endpoints, but without being able to bootstrap the service with user credentials, manual action is still required. I love the kuma UI, but I'm forced to use gatus.

deekerman commented

2026-02-28 03:12:56 -05:00

Author

Owner

@Twinki14 commented on GitHub (Jan 3, 2024):

I am disappointed that this minimal feature of configuring credentials via env var is not supported. The strong stance against config files make this impossible to deploy via GitOps. I was going to go the route of using the API to add endpoints, but without being able to bootstrap the service with user credentials, manual action is still required.

I love the kuma UI, but I'm forced to use gatus.

Exactly my situation, I can't use Kuma UI at all in GitOps.

It is technically possible by editing Kuma's SQLite DB with some type of SQLite CLI. I don't believe the DB is protected with credentials, but this is such a hacky workaround for something so simple.

@Twinki14 commented on GitHub (Jan 3, 2024): > I am disappointed that this minimal feature of configuring credentials via env var is not supported. The strong stance against config files make this impossible to deploy via GitOps. I was going to go the route of using the API to add endpoints, but without being able to bootstrap the service with user credentials, manual action is still required. > > I love the kuma UI, but I'm forced to use gatus. Exactly my situation, I can't use Kuma UI at all in GitOps. It is technically possible by editing Kuma's SQLite DB with some type of SQLite CLI. I don't believe the DB is protected with credentials, but this is such a hacky workaround for something so simple.

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@gl-yziquel commented on GitHub (Jan 9, 2024):

This situation is ridiculous. I've been coming over the past few months regularly to uptime kuma and would love to use it.

It's however next to impossible to get in the documentation some setup instructions for username and password.

I guess I'll come back in two months or so to check how that has improved. Or not.

Is it because I'm a dinosaur that has toyed with 286 CPU in real mode as a kid that I don't get this new modern vibe of having unintuitively documented applications where you have to guess the documentation ??

@gl-yziquel commented on GitHub (Jan 9, 2024): This situation is ridiculous. I've been coming over the past few months regularly to uptime kuma and would love to use it. It's however next to impossible to get in the documentation some setup instructions for username and password. I guess I'll come back in two months or so to check how that has improved. Or not. Is it because I'm a dinosaur that has toyed with 286 CPU in real mode as a kid that I don't get this new modern vibe of having unintuitively documented applications where you have to guess the documentation ??

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@CommanderStorm commented on GitHub (Jan 9, 2024):

It's impossible to get in the documentation some setup instructions for username and password

When you boot up the docker image or install via node, this is the first thing you are asked about on the setup screen.

The rest of your comment is not quite formulated as a comment but rather is spreading non-productive, passive-aggressive toxicity
⇒ I am going to ignore those questions/ comments

I am instead going to talk about our docs.
Yes, our documentation may be lacking in some parts.
I don't know what you are concretely missing. What is your expectation from the docs?

Important

What you're forgetting is that you're not talking to some faceless gigacorp here.
Instead, this is an organisation run by human beings who have decided to donate their time working on something for free to the world.

What you might not expect is that this application has for most of its existance been maintained by louis alone (along with contributors submitting parts).
Only very recently Nelson and I came onboard to be juinior-maintainers as well.
As with every other open-source project we heavily rely on constructive feedback and contributions from our community where we are failing and how to improve.

@chakflying you stated in https://github.com/louislam/uptime-kuma/pull/4171#issuecomment-1840095650 that you are planning something.
Do you think a pinned issue with a plan of action and a call for contributions may be a part of a solution?

@CommanderStorm commented on GitHub (Jan 9, 2024): > It's impossible to get in the documentation some setup instructions for username and password When you boot up the docker image or install via node, this is the first thing you are asked about on the setup screen. The rest of your comment is not quite formulated as a comment but rather is spreading non-productive, passive-aggressive toxicity ⇒ I am going to ignore those questions/ comments I am instead going to talk about our docs. Yes, [our documentation](https://github.com/louislam/uptime-kuma/wiki) may be lacking in some parts. I don't know what you are concretely missing. What is your expectation from the docs? > [!IMPORTANT] > What you're forgetting is that you're not talking to some faceless gigacorp here. Instead, this is an organisation run by human beings who have decided to donate their time working on something for free to the world. > > What you might not expect is that this application has for most of its existance been maintained by louis alone (along with contributors submitting parts). > Only very recently Nelson and I came onboard to be juinior-maintainers as well. > As with every other open-source project we heavily rely on **constructive feedback** and contributions from our community where we are failing and how to improve. @chakflying you stated in https://github.com/louislam/uptime-kuma/pull/4171#issuecomment-1840095650 that you are planning something. Do you think a pinned issue with a plan of action and a call for contributions may be a part of a solution?

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@gl-yziquel commented on GitHub (Jan 10, 2024):

The rest of your comment is not quite formulated as a comment but rather is spreading non-productive, passive-aggressive toxicity ⇒ I am going to ignore those questions/ comments

Absolutely. I agree. I was getting annoyed. Apologies.

But it indeed is rather a pain not to have control from the command line. The reality is that I had uptime kuma installed a few months ago, had it running, and as I am not running it regularly, each time I come back, I look at the docs, and fail to find useful information about how the password is set up. It was indeed set up, and I spent quite a few hours running around with a web screen asking me for a password, and nowhere in the documentation where this is handled explicitly.

More seriously: credential management should really be the first thing you see when reading a documentation about such a webapp. Spending four hours roaming around the documentation while multitasking is simply a time waster.

I am instead going to talk about our docs. Yes, our documentation may be lacking in some parts. I don't know what you are concretely missing. What is your expectation from the docs?

Information about credential management in the first pages. State explicitly (in text mode, I read text, not emojis or images which do not show up in a terminal) that the password and username is configured initially at first login (this way, if you do not see a screen asking to initialise password, you may easily infer without wasting time that it likely is already initialised). Plus a link to the tool to manage the password to reinitialise it, just below.

What you're forgetting is that you're not talking to some faceless gigacorp here. Instead, this is an organisation run by human beings who have decided to donate their time working on something for free to the world.

I am not forgetting that. I was annoyed. It's fairly obvious that this isn't DirectXShaderCompiler with both MS and Google committing.

What you might not expect is that this application has for most of its existance been maintained by louis alone (along with contributors submitting parts). Only very recently Nelson and I came onboard to be juinior-maintainers as well. As with every other open-source project we heavily rely on constructive feedback and contributions from our community where we are failing and how to improve.

Ranting, which I did, is by no way demeaning the work done, which is obviously very good. I can swear and congratulate you at the same time.

There is however a culture mismatch between people like me who grew up with a DOS command line and people putting docker containers everywhere. And it shows in the way password management is here handled and this thread about the lack of initialisation by environment variables.

I want explicit installation procedures. Not "here is a docker container, you've got nothing else to do". Which usually is just skimming over the real configuration issues.

I know writing documentation is a pain.

@gl-yziquel commented on GitHub (Jan 10, 2024): > The rest of your comment is not quite formulated as a comment but rather is spreading non-productive, passive-aggressive toxicity ⇒ I am going to ignore those questions/ comments Absolutely. I agree. I was getting annoyed. Apologies. But it indeed is rather a pain not to have control from the command line. The reality is that I had uptime kuma installed a few months ago, had it running, and as I am not running it regularly, each time I come back, I look at the docs, and fail to find useful information about how the password is set up. It was indeed set up, and I spent quite a few hours running around with a web screen asking me for a password, and nowhere in the documentation where this is handled explicitly. More seriously: credential management should really be the first thing you see when reading a documentation about such a webapp. Spending four hours roaming around the documentation while multitasking is simply a time waster. > I am instead going to talk about our docs. Yes, [our documentation](https://github.com/louislam/uptime-kuma/wiki) may be lacking in some parts. I don't know what you are concretely missing. What is your expectation from the docs? Information about credential management in the first pages. State explicitly (in text mode, I read text, not emojis or images which do not show up in a terminal) that the password and username is configured initially at first login (this way, if you do not see a screen asking to initialise password, you may **easily** infer without wasting time that it likely is already initialised). Plus a link to the tool to manage the password to reinitialise it, just below. > What you're forgetting is that you're not talking to some faceless gigacorp here. Instead, this is an organisation run by human beings who have decided to donate their time working on something for free to the world. I am not forgetting that. I was annoyed. It's fairly obvious that this isn't DirectXShaderCompiler with both MS and Google committing. > What you might not expect is that this application has for most of its existance been maintained by louis alone (along with contributors submitting parts). Only very recently Nelson and I came onboard to be juinior-maintainers as well. As with every other open-source project we heavily rely on **constructive feedback** and contributions from our community where we are failing and how to improve. Ranting, which I did, is by no way demeaning the work done, which is obviously very good. I can swear and congratulate you at the same time. There is however a culture mismatch between people like me who grew up with a DOS command line and people putting docker containers everywhere. And it shows in the way password management is here handled and this thread about the lack of initialisation by environment variables. I want explicit installation procedures. Not "here is a docker container, you've got nothing else to do". Which usually is just skimming over the real configuration issues. I know writing documentation is a pain.

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@magicalbob commented on GitHub (Jan 21, 2024):

I would have liked this feature to be available too, so that my IaC could just make sure the initial user is present. As it happens I've created a selenium script in python to set the initial user up in my git https://github.com/magicalbob/k8s_uptime_kuma/blob/master/python/create_user.py

@magicalbob commented on GitHub (Jan 21, 2024): I would have liked this feature to be available too, so that my IaC could just make sure the initial user is present. As it happens I've created a selenium script in python to set the initial user up in my git https://github.com/magicalbob/k8s_uptime_kuma/blob/master/python/create_user.py

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@alehostert commented on GitHub (Jul 15, 2025):

Hello from 2025.

Still not able to automatically add an user via cli/.env.

I'm bumping this one in hope that this feature become alive :)

@alehostert commented on GitHub (Jul 15, 2025): Hello from 2025. Still not able to automatically add an user via cli/.env. I'm bumping this one in hope that this feature become alive :)

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@seriouslag commented on GitHub (Jan 10, 2026):

I would like the users to be populated from my OIDC provider or auth disabled on initial launch by the config so I can use authentik to secure the app and not need to manually disable auth.
Enjoying the project, thank you!

@seriouslag commented on GitHub (Jan 10, 2026): I would like the users to be populated from my OIDC provider or auth disabled on initial launch by the config so I can use authentik to secure the app and not need to manually disable auth. Enjoying the project, thank you!

deekerman commented

2026-02-28 03:12:57 -05:00

Author

Owner

@CommanderStorm commented on GitHub (Jan 10, 2026):

@seriouslag a bit off topic to this issue. If you want to contribute towards that goal, the right issue is

https://github.com/louislam/uptime-kuma/issues/6200

@CommanderStorm commented on GitHub (Jan 10, 2026): @seriouslag a bit off topic to this issue. If you want to contribute towards that goal, the right issue is - https://github.com/louislam/uptime-kuma/issues/6200

Rows
Columns

Environment Variables for initial user-creation #2955

⚠️ Please verify that this feature request has NOT been suggested before.

🏷️ Feature Request Type

🔖 Feature description

✔️ Solution

❓ Alternatives

📝 Additional Context