Local image service
The CLI emits photograph URLs by default. The companion service makes them available to Obsidian Desktop on the same Mac. A URL names a photograph of a post you can copy a message link to: a post of a channel or a supergroup, private ones included. Private chats and basic groups have no such link and get no URL. Videos, GIFs, image documents, web previews, paid and expiring media are outside this version.
A URL is a name, not a download. Giving it writes nothing: a URL nobody opens leaves no trace. The service saves the photograph the first time someone opens the URL and serves the copy from then on, without Telegram. A post deleted before anyone opened its photographs takes them with it.
Install and start
One Homebrew Formula, octolab/tap/indexit, installs both the CLI and its
service definition. They use the same binary and update together. For a new
installation, run brew install --formula octolab/tap/indexit.
If you installed the previous Cask, migrate once after the Formula is published:
brew update
brew uninstall --cask octolab/tap/indexit
brew install --formula octolab/tap/indexitDo not use --zap: keep your Telegram configuration and saved photographs.
Then start the service and check it:
brew services start octolab/tap/indexit
curl -fsS -o /dev/null http://indexit.localhost:17840/Photograph URLs point to http://indexit.localhost:17840/. A .localhost name
always means this Mac: macOS resolves it to loopback, 127.0.0.1 and ::1,
without a hosts entry, sudo or any other system setup. The image service runs
as your normal user and listens only on loopback, 127.0.0.1:17840 and
[::1]:17840; without IPv6 it serves on 127.0.0.1 alone. Installing the
package alone does not start it. Do not run sudo brew services.
The service reads the same ~/.config/indexit/.env and Telegram session as the CLI.
The service ignores working-directory .env files and uses the shared config
directory; explicit --env-file and INDEXIT_ENV_FILE still override it. Ordinary
CLI commands retain their working-directory lookup. Sign in through the CLI before
requesting an uncached photograph. No separate HTTP proxy is needed.
On the first request for a photograph, the service finds its channel by
itself: a channel it found before, the CLIβs peer cache, which it only reads,
your dialogs with the archive, and the channelβs cached username. If the
account cannot see the channel, the URL answers 404: fetch the post on this
Mac and open it again. A post or a photograph gone from Telegram, or a
photograph the author replaced, answers 410: an old URL never shows another
picture.
Dashboard
Open http://indexit.localhost:17840/Β in a browser. The page shows how many photographs this Mac keeps and their size, the free space on the disk, how many requests the service answered from disk and per download, the days photographs were saved, the channels they come from and the ten latest, with links to the photograph and to its Telegram post. It updates by itself every 15 seconds while it is open.
It counts the photographs on disk, nothing else: a fetch registers nothing.
It also lists what needs a look: photographs Telegram answered no longer
exist, failed requests, and files in the image directory that are not
photographs. /api/v1/stats returns the same numbers as JSON.
The page lists every saved photograph, so it answers only on this Mac: to an
address of loopback, localhost or a .localhost name, and not through a
proxy. Photograph URLs work as before. To turn the page off, set
dashboard = false under [service] and restart the service.
The days come from the dates of the image files: a photograph restored from a backup counts as saved on the day it was restored. The calendar of the last 26 weeks appears once the oldest photograph is two weeks old, with a table of the same days for the keyboard and screen readers. Request counts start with v0.3.1 and cover the last 13 months. Browsers keep photographs for a year, so a view is not always a request.
Configuration
indexit service run writes ~/.config/indexit/config.toml, or
$XDG_CONFIG_HOME/indexit/config.toml, next to the shared .env, when there
is none: every key is there, commented out with its default. It never changes
an existing file. brew services starts the service without your shellβs
environment, so it uses ~/.config even if you set XDG_CONFIG_HOME; the
service log names the file it wrote.
Change the URL origin
Each export carries its URLs as they were written. To write new ones with
another origin, uncomment origin under [service]:
[service]
origin = "http://photos.localhost:17840"The origin is http:// or https://, a host name or an IPv4 address and an
optional port, with nothing after them but an optional slash. Any .localhost
name on port 17840 reaches the service as well. Another port, or a host that
does not resolve to this Mac, needs your own proxy in front of the service,
which keeps listening on its loopback addresses. The CLI and the service read
the same file, which accepts only the keys of the template: an unknown key or
a malformed value stops the command with an error naming the file and the
key. Without an origin, URLs use http://indexit.localhost:17840.
With an origin outside this Mac, the dashboard is off unless you set
dashboard = true: the proxy in front of the service would show it to
everyone who reaches the proxy.
Share the photographs between computers
The saved photographs can live apart from the rest of the data, in a folder
another computer shares, such as one in Google Drive. Uncomment images under
[service] with an absolute path or one starting with ~/:
[service]
images = "~/Google Drive/indexit/images"A photographβs path is its URLβs path under that folder:
images/c<channel>/<message>/p<photo>.jpg. Another computer that runs the
service with the same folder shows the same photographs by the same URLs,
without asking Telegram. A photograph neither has saved is filled by whichever
service is asked, if its account can see the channel. A service writes a
photograph to a temporary file next to it, named for the computer, checks that
it is a complete JPEG, then moves it into place, and never replaces a saved
one. A conflict copy the cloud folder leaves, p⦠(1).jpg, is neither served
nor counted.
Storage and availability
Data lives in ~/.local/share/indexit, or $XDG_DATA_HOME/indexit.
INDEXIT_DATA_DIR overrides the complete directory. The photographs are in
images/ of it unless images under [service] says otherwise; the locks of
the downloads and the request counts stay in the data directory of each
computer. stats/ holds the request counts of the dashboard, one small file a
month; the service removes months older than 13. Deleting it resets the counts
and nothing else.
There is no automatic eviction or storage limit: disk use grows as images are read.
Keep a backup if a local copy may become the only surviving photograph.
A saved image needs no Telegram session or network, and a request for it never
reaches Telegram. A saved file that cannot be read answers 503 and is never
downloaded again; check the image directory. A cold request waits for any
running CLI Telegram operation, for at most two minutes; retry a failed request.
Cached requests continue during that wait. Concurrent downloads of one photo are
coalesced across processes and incomplete files are never published.
URLs contain no secret token. Any local client knowing a URL can read its image. They are not promised to work from a phone, another machine or a web page that blocks local HTTP. Clearing browser cache does not delete the saved photograph.
If Obsidian opens a note before the service is ready, failed image elements may
remain visible after the service starts. Check
curl -fsS -o /dev/null http://indexit.localhost:17840/, then reopen the note
or switch to reading view to reload its images.
Upgrade, stop and remove
brew update
brew upgrade --formula octolab/tap/indexit
brew services restart octolab/tap/indexit
brew services stop octolab/tap/indexitOld URLs, configuration and saved data survive updates and restarts. To remove the Formula:
brew services stop octolab/tap/indexit
brew uninstall --formula octolab/tap/indexitUninstall preserves the photographs. Explicitly remove files under images/
only when you intend to discard those copies, and leave your Telegram
configuration alone. Deleted remote sources cannot be recovered.
Local development and Linux
go build -o ./bin/indexit .
./bin/indexit service runRepeat --listen with a literal loopback address and port, such as
--listen 127.0.0.1:8080, to replace both default addresses. Without
--listen, a system without IPv6 serves on 127.0.0.1 alone.
The ordinary Linux CLI still works; automatic Linux service setup is outside
this iteration. The dashboard works the same way at the address you listen on,
such as http://localhost:8080/.