mirror of
https://github.com/actualbudget/actual.git
synced 2026-03-10 20:23:07 -05:00
[Bug]: missing icon in Safari and PWA on iOS #1895
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/actual#1895
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @felixguilherme on GitHub (Feb 25, 2025).
Verified issue does not already exist?
What happened?
The Actual favicon is missing in the Safari browser and therefore in PWA installs on iOS 18.3.1. It works as expected on macOS 15.3.1 with Safari 18.3.
Actual version: app: v25.1.0, server: v25.1.0
iOS:
macOS:
How can we reproduce the issue?
Where are you hosting Actual?
Docker
What browsers are you seeing the problem on?
Safari
Operating System
Mobile Device
@Ctrl-Alb commented on GitHub (Feb 27, 2025):
Before seeing your post I was going to open an issue because I encountered the same problem
@alecbakholdin commented on GitHub (Mar 15, 2025):
I attempted this on iOS 18.2 on Safari and it seems to be working. Are you still experiencing this issue?
@Ctrl-Alb commented on GitHub (Mar 15, 2025):
Hi @alecbakholdin, unfortunately, I'm still experiencing the issue.
I'm running the latest Actual Budget server version and the latest iOS version (18.3.2).
The issue is well described by @felixguilherme, I'll add one thing about my use case that hopefully could help in figuring out the problem.
The icon is always missing, except when I open the share sheet in Safari while on the Actual server page, where the icon is displayed correctly (see the image).
@alecbakholdin commented on GitHub (Mar 18, 2025):
@CTRL-panino see below Stack Overflow post which explains your problem. It has to do with the fact that you're using a self-signed certificate. There's unfortunately not much we can do about this issue, I think, though there appear to be some steps you can take to register your certificate with iOS: https://stackoverflow.com/questions/6807349/why-wont-this-apple-touch-icon-work
@Ctrl-Alb commented on GitHub (Mar 19, 2025):
Thank you for your help. I tried downloading and installing the certificate, but it doesn't seem to be working. Here are the steps I followed:
selfhost.crtfile from my Actual Budget serverAfter these steps, when I try to re-create the Actual Budget web-app, the missing icon bug is still present. Am I doing something wrong?
@alecbakholdin commented on GitHub (Mar 21, 2025):
I was able to install the certificate by just clicking on the file. After downloading the file to my iPhone, I clicked on the file in Downloads:
It prompted me to install it:
I go to settings, and I see this:
Then I click on install in the top right:
After these steps, I do see the profile in VPN & Device Management:
Let me know if this helps! I wasn't able to get my docker-compose to work with the self-signed certs, so this is the most I can help with right now, I'm sorry!
@Ctrl-Alb commented on GitHub (Mar 21, 2025):
Thank you very much, I really appreciate your help.
The only differences between what I did previously and your new comment are:
Your certificate is called
localhost, while I created mine following this guide, and it was namedselfhost.crt. Did I choose the right one?I see it there, too. However, according to the link you sent in your previous comment, I should also see it in
Settings -> General -> Info -> Certificate Trust Settings, but it doesn't appear there@ngocphamm commented on GitHub (Apr 1, 2025):
I think this is happening to me too, even when I have Actual Budget behind Cloudflare Access tunnel, which is indeed under HTTPS. Favicon shows the Actual logo properly, but the
Add to Home Screenlogo is still the generic A letter.@ngocphamm commented on GitHub (May 2, 2025):
Update: The problem I have is with Cloudflare Access, and not Actual. Because there is authentication with Cloudflare required before I can access Actual, when creating the home screen shortcut/bookmark, iOS cannot access the icon file. Creating a bypass rule like
/*.pnghelps. I see the proper icon now!@alecbakholdin commented on GitHub (May 2, 2025):
Glad you figured it out!
@Ctrl-Alb commented on GitHub (Jun 5, 2025):
Hi @matt-fidd ,
I’d like to point out that unfortunately the problem hasn’t been solved.
Maybe the Cloudflare-related bug has been solved but the one described by me and by the author of the issue has not
@james4141 commented on GitHub (Dec 1, 2025):
Spent a bit of time troubleshooting this as I have this issue as well, and can confirm this is a certificate trust issue, and not an issue with Actual itself. However, I am interested in identifying and documenting a process that works, rather than just closing this out by stating it's an iOS issue .
TLDR: Issue is cause by a self-signed certificate that is not trusted by iOS. The documented OpenSSL commands provided result in a certificate that's not fully compatible with iOS, plus additional steps are required in iOS to enable Full Trust.
This Apple KB article shows how to enable Full Trust. The OpenSSL commands provided at Activating HTTPS creates a self-signed server cert and key that is not signed by a separate Root certificate. This is why @CTRL-panino and others aren't seeing the option shown in the Apple KB - there needs to be a certificate chain for iOS to follow.
To verify this, I created my own Root certificate, used it to sign a server cert for Actual, used AirDrop to copy/install the Root cert to the iOS device, then enable Full Trust. I can confirm it works - the are no certificate warnings, and the correct app icon appears.
I am unsure what to recommend here and open to suggestions. OpenSSL can be used to create a compatible cert chain, but there's a fair amount of complexity over the single command we've currently got. And then, you've still got to get the cert onto the iOS device (probably via AirDrop or Mail), then go into Settings to install it, then to another location in Settings to enable Full Trust. None of this is extremely difficult.. it's just more steps.
I'm also not sure how frequently this process needs to be completed. There is a new(ish) limit to how long certificates can be valid, but it only applies to certificates issues to one of the Root CA's preinstalled with iOS - meaning it does not apply to something you created with OpenSSL. This guy determined the maximum validity for certificates issued by a private CA is 825 days, or about 2 years plus a few months - just long enough to completely forget everything you had to do in order to get it working, when it expires 2 years later.
Because there is a dependency on functioning SSL for core features of Actual to work, like Bank Sync and usage of iOS devices, it might be helpful if Actual could generate the necessary certs on startup, if there is no valid cert already defined/installed.
Also - there have also been a number of Discord users reporting an iOS client that randomly disconnects from the server and can only be fixed by deleting the PWA, clearing Safari, browsing to Actual again, clicking through the certificate warning, and reinstalling the PWA. I suspect clicking "visit this website" in Safari creates a temporary exception, and once that timer runs out, everything breaks - resolving this trust issue may fix this as well.
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
Hi @james4141, thank you for the in-depth explanation.
Could you please share a step-by-step list so I can replicate your setup?
@james4141 commented on GitHub (Dec 3, 2025):
Sure, give this a try and let us know if it worked for you. I had to go back and re-create steps so I may have missed something. You didn't specify which device you're using to create certs, so I'll assume Mac, but these commands will work on Linux as well. If you're on Windows, I can try to help walk you through it.
Open up a terminal and run these commands to create a new directory, change into it, and create a new file:
Paste this block of text into the nano editor. Change DNS.1 and IP.1 to the correct server name and IP you'll be using to access. This needs to exactly match what you type on your iPhone browser, excluding 'https://' and ':5006'. If you don't use a DNS hostname at all, you can delete this line.
Press Ctrl-X to exit, then 'y' and Enter to save.
Run these commands to generate a root key and certificate, then a server key and certificate signed by the root certificate. You'll be prompted twice for certificate details (CN, Org, Country, etc). Enter what you want, these aren't terribly important. Common Name (CN) should be your server name or IP. If you're prompted to 'extra' attributes, leave those blank and press Enter.
You should now have a directory named actual-cert with about 7 files in it. The 3 files you'll need are:
Install the server.key and server.crt in your Actual instance. I use Docker so created a config.json file like this:
Now we need to get the root certificate installed on your phone. You should be able to email the file to yourself, but I chose to use AirDrop. Open the actual-cert directory in Finder then drag and hold the rootCA.pem over the AirDrop icon on the left. Your phone should appear in the main window - if it doesn't, wake up your phone and try again.
You'll be prompted on your phone where to install the certificate - tap iPhone. Tap Close. Go to Settings > Profile Downloaded. Tap Install, enter your passcode, then tap Install 2 times.
Next, go to Settings > General > About > Certificate Trust Settings. Enable Full Trust for the RootCA you just created.
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
Thank you very much, you've been super helpful! I'll test this when I come back home and I'll let you know.
I am using Debian (and Docker) for the Actual server and iOS and macOS as clients. So, I assume the steps you described will be perfectly fine for my setup as well
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
I'm encountering an error while trying to follow the steps you described. Here's what I've done so far:
server.extfile in theactual-certfolder. This file contains the following lines:actual-certfolder, I ran the commands:I entered
ITas the Country Name and192.168.1.28as the Common Name, leaving the other fields blank.This command returns the following error message:
@james4141 commented on GitHub (Dec 3, 2025):
Looks like I forgot a line - give this a try then pick up where you left off:
openssl req -new -key server.key -out server.csrEdited my comment above to include this as well.
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
I have followed the steps you described, but now I can't have access to the Actual server.
I tried restarting my Debian machine and even reinstalled Actual Budget (and copying
config.json,server.keyandserver.crtin the/datafolder), but now I can't access it either via HTTP or HTTPS.It’s not a big issue since I didn’t have any personal data in this Actual instance.
Do you have any suggestions to fix it?
@james4141 commented on GitHub (Dec 3, 2025):
Just to confirm - your file is named config.json and not .jsonc? Are there any container logs? I run mine on Unraid so I'm not certain on the command for that, but this may help
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
You're right, I mistyped, I meant
config.json(I updated previous my comment)@james4141 commented on GitHub (Dec 3, 2025):
Is the container running or does it fail and stop? Logs would be helpful if you are able to retrieve anything
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
I figured out the problem: in the
config.jsonfile I had writtenselfhost.key(the file name I used before) instead ofserver.key(the file name in your guide).After correcting the issue, not only does the Actual Budget work correctly, it also shows the icon on the home screen!
This means that the steps described in your comment worked perfectly.
Great, thank you very much!
@james4141 commented on GitHub (Dec 3, 2025):
Glad to hear. So you are aware, the certificate you created for Actual is valid for 825 days - that's supposedly the maximum validity period that iOS will accept for a certificate issued by private CA. Before that runs out, you'd need to run the last 2 commands to generate a new certificate using the same key (or use the last 3 commands to also generate a new key). Then copy the certificate to your server. You wouldn't need to repeat the root CA process on your iPhone since that's valid for 10 years, though I'm not sure if this carries over when upgrading phones.
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
Thank you for the explanation, I'll keep it in mind.
One last question: in order to make things work not only on my iOS client but also on my macOS client, what should I do?
Should I simply import the
rootCA.pemfile on my Mac?@james4141 commented on GitHub (Dec 3, 2025):
Open Keychain Access, select System keychain, and drop the RootCA.pem there. You may need to search/filter to find it, open that up and select Always Trust.
If you use Firefox on Mac you may need to add it there as well, I think Firefox uses its own cert store.
@Ctrl-Alb commented on GitHub (Dec 3, 2025):
Perfect, thank you very much :)
You’ve been super helpful
@james4141 commented on GitHub (Dec 3, 2025):
Thanks. Just wanted to get to the bottom of this as it gets asked on Discord quite often.
Tagging @youngcw because we need an adult 😬 I posted a potential workound for the iOS SSL/certificate issues when using a self-signed cert. I believe this may also fix issues where iOS clients randomly disconnect from the server. Also, I've found that using https://app.actualbudget.org won't work on iOS devices when the server is using an Untrusted certificate.
Do you think the best resolution here is to update the HTTPS documentation?
@james4141 commented on GitHub (Jan 12, 2026):
@Ctrl-Alb Just wanted to follow up and see if this is still working for you - have you had any problems where your iOS client stopped working after getting these certs up and running?
@Ctrl-Alb commented on GitHub (Jan 12, 2026):
Hi @james4141, since I followed your suggestion, the icon is displayed correctly and, as far as I know, I haven’t encountered any problems with the certificates.
So, it seems that everything’s working fine :)