📦➔🦋 Store and retrieve files on the Atmosphere
1<h1 align="center">
2 Atfile
3</h1>
4
5<p align="center">
6 Store and retrieve files on the <a href="https://atproto.com/">Atmosphere</a> (like <a href="https://bsky.app">Bluesky</a> or <a href="https://tngl.sh">Tangled</a>)<br />
7 <em>Written entirely in Bash Shell. No <span title="Deno is pretty cool tho">NodeJS</span> here!</em>
8</p>
9
10<hr />
11
12## ✨ Quick Start
13
14```sh
15curl -sSL https://zio.sh/atfile.sh | bash
16echo 'ATFILE_USERNAME="<your-atproto-username>"' > ~/.config/atfile.env # e.g. alice.bsky.social, did:plc:wshs7t2adsemcrrd4snkeqli, did:web:zio.sh
17echo 'ATFILE_PASSWORD="<your-atproto-password>"' >> ~/.config/atfile.env
18atfile help
19```
20
21## 👀 Detailed Usage
22
23### ✅ Requirements
24
25* **OS¹**
26 * 🟡 **Linux**: GNU, MinGW and Termux only; musl² not supported
27 * 🟢 **macOS**: Compatible with built-in version of Bash (3.2)
28 * 🔴 **Windows**: No native version available
29 * Run with MinGW (Cygwin, Git Bash, MSYS2, etc.) or WSL (see Linux caveats above)
30 * 🟢 __*BSD__: FreeBSD, NetBSD, OpenBSD, and other *BSD's
31 * 🟢 **Haiku**: [Yes, really](https://bsky.app/profile/did:plc:kv7sv4lynbv5s6gdhn5r5vcw/post/3lboqznyqgs26)
32 * 🔴 **Solaris**: <span title="Don't we all?">Has issues</span>; low priority
33 * 🔴 **SerenityOS**: Untested
34* **Bash³:** 3.x or later
35* **Packages**
36 * [`curl`](https://curl.se)
37 * [ExifTool (`exiftool`)](https://exiftool.org) _(optional: set `ATFILE_DISABLE_NI_EXIFTOOL=1` to ignore)_
38 * [`file`](https://www.darwinsys.com/file) _(only on *BSD, macOS, or Linux)_
39 * [GnuPG (`gpg`)](https://gnupg.org) _(optional: needed for `upload-crypt`, `fetch-crypt`)_
40 * [`jq`](https://jqlang.github.io/jq)
41 * [MediaInfo (`mediainfo`)](https://mediaarea.net/en/MediaInfo) _(optional: set `ATFILE_DISABLE_NI_MEDIAINFO=1` to ignore)_
42 * `md5sum` _(optional: set `ATFILE_DISABLE_NI_MD5SUM=1` to ignore)_
43 * Both GNU and BusyBox versions supported
44 * `sed`
45 * Only GNU version supported
46 * [`websocat`](https://github.com/vi/websocat) _(optional: needed for `stream`)_
47* **Atproto account**
48 * Limit the amount of files you upload, and avoid copyrighted files, if using a managed PDS you don't own yourself
49 * Supports accounts with `did:plc` or `did:web` identities
50 * Supports PDSs running [Bluesky PDS](https://github.com/bluesky-social/pds)
51 * Other PDSs remain untested, but if they implement standard `com.atproto.*` endpoints and blob storage, there should be no reason these won't work
52 * Filesize limits cannot be automatically detected. By default, this is 100MB
53 * To change this on Bluesky PDS, set `PDS_BLOB_UPLOAD_LIMIT=<bytes>`
54 * If the PDS is running behind Cloudflare, the Free plan imposes a 100MB upload limit
55 * This tool, nor setting a higher filesize limit, **does not workaround [video upload limits on Bluesky](https://bsky.social/about/blog/09-11-2024-video).** Videos are served via a [CDN](https://video.bsky.app), and adding larger videos to post records yields errors
56
57### ⬇️ Downloading & Installing
58
59There are three ways of installing Atfile. Either:
60
61#### Automatic ("`curl|bash`")
62
63```
64curl -sSL https://zio.sh/atfile.sh | bash
65```
66
67This will automatically fetch the latest version of Atfile and install it in an appropriate location, as well as creating a blank configuration file. Once downloaded and installed, the locations used will be output. They are as follows:
68
69* __Linux/*BSD/Solaris/SerenityOS__
70 * Install: `$HOME/.local/bin/atfile`
71 * As `sudo`/`root`: `/usr/local/bin/atfile`
72 * On **Termux:** `/usr/bin/atfile`
73 * Config: `$HOME/.config/atfile.env`, **or** `$XDG_CONFIG_HOME/atfile.env` (if set)
74* **macOS**
75 * Install: `$HOME/.local/bin/atfile`
76 * As `sudo`/`root`: `/usr/local/bin/atfile`
77 * Config: `$HOME/Library/Application Support/atfile.env`
78* **Haiku**
79 * Install: `/boot/system/non-packaged/bin/atfile`
80 * Config: `$HOME/config/settings/atfile.env`
81
82#### Manually
83
84See [tags on @zio.sh/atfile](https://tangled.org/@zio.sh/atfile/tags), and download the required version under **Artifacts** — this can be stored and run from anywhere (and is identical to the version `curl|bash` fetched. Consider renaming to `atfile.sh` (as Atfile can update itself, making a fixed version in the filename nonsensical), and mark as executable (with `chmod +x atfile.sh`).
85
86Config locations are identical to those above (see **Automatic ("`curl|bash`")** above).
87
88#### Repository
89
90If you've pulled this repository, you can also use Atfile by simply calling `./atfile.sh` — it functions just as a regular compiled version of Atfile, including reading from the same config file. Debug messages are turned on by default: disable these by setting `ATFILE_DEBUG=0`.
91
92Config locations are identical to those above (see **Automatic ("`curl|bash`")** above).
93
94**Using a development version against your Atproto account could potentially inadvertently damage records.**
95
96### ⌨️ Using
97
98See `atfile help`.
99
100## 🏗️ Building
101
102To compile, run `./atfile.sh build`. The built version will be available at `./bin/atfile-<version>[+git.<hash>].sh`.
103
104### Environment variables
105
106Various environment variables can be exported to control various aspects of the development version. These are as follows:
107
108* `ATFILE_DEVEL_DIST_USERNAME` <em><string></em><br />_(Todo)_. During runtime, this is set to `$did` in `atfile.sh` (see **🏗️ Building ➔ Meta**). Ideally, you should not set this variable as updates in the built version will not be fetched from the correct place
109* `ATFILE_DEVEL_DIST_PASSWORD` <em><string></em><br />_(Todo)_
110* `ATFILE_DEVEL_ENABLE_PIPING` <em><int> (default: `0`)</em><br />Allow piping (useful to test installation) _(e.g. `cat ./atfile.sh | bash`)_
111* `ATFILE_DEVEL_ENABLE_PUBLISH` <em><int> (default: `0`)</em><br />Publish build to Atproto repository (to allow for updating) as the last step when running `build`. Several requirements must be fulfilled:
112 * `ATFILE_DEVEL_DIST_USERNAME` must be set
113 * `ATFILE_DEVEL_DIST_PASSWORD` must be set
114 * No tests should return an **Error** (**Warning** is acceptable)
115 * Git commit must be <a href="https://git-scm.com/docs/git-tag">tagged</a>
116
117Other `ATFILE_DEVEL_` environment variables are visible in the codebase, but these are computed internally and cannot be set/modified.
118
119### Directives
120
121Various build directives can be set in files to control various aspects of the development version. These are set with `# atfile-devel=` directive at the top of the file, using commas to separate values. These are as follows:
122
123* `ignore-build`<br />Do not include file in the final compiled build
124
125### Meta
126
127Various meta variables can be set to be available in the final compiled build (usually found in `help`). These are found in `atfile.sh` under `# Meta`. These are as follows:
128
129* `author` <em><string></em><br />Copyright author
130* `did` <em><did></em><br />DID of copyright author. Also used as the source for published builds, unless `ATFILE_DEVEL_DIST_USERNAME` is set (see **🏗️ Building ➔ Environment variables**)
131* `repo` <em><uri></em><br />Repository URL of source code
132* `version` <em><string></em><br />Version in the format of `<major>.<minor>[.<patch>]`. **Not following this format will cause unintended issues.** Git hashes (`+git.abc1234`) are added automatically during build when a <a href="https://git-scm.com/docs/git-tag">git tag</a> is **not** applied to the current commit
133* `year` <em><int></em><br />Copyright year
134
135## ⌨️ Contributing
136
137Development takes place on [Tangled (@zio.sh/atfile)](https://tangled.sh/@zio.sh/atfile), with [GitHub (ziodotsh/atfile)](https://github.com/ziodotsh/atfile) acting as a mirror. Use Tangled for your contributions, for both <a href="https://tangled.org/@zio.sh/atfile/issues">Issues</a> and <a href="https://tangled.org/@zio.sh/atfile/pulls">Pulls</a>. As Tangled is powered by Atproto, you already have an account (unsure? Try <a href="https://tangled.org/login">logging in with your Bluesky handle</a>).
138
139When submitting Pulls, **target the `dev` branch**: `main` is the current stable production version, and Pulls will be rejected targeting this branch.
140
141## 🤝 Acknowledgements
142
143* **Paul Frazee** — [🦋 @pfrazee.com](https://bsky.app/profile/did:plc:ragtjsm2j2vknwkz3zp4oxrd)<br /><a href="https://bsky.app/profile/did:plc:ragtjsm2j2vknwkz3zp4oxrd/post/3l63zzvthqj2o">His kind words</a>
144* **Laurens Hof** — [🦋 @laurenshof.online](https://bsky.app/profile/did:plc:mdjhvva6vlrswsj26cftjttd)<br />Featuring Atfile on [The Fediverse Report](https://fediversereport.com): _["Last Week in the ATmosphere – Oct 2024 week 4"](https://fediversereport.com/last-week-in-the-atmosphere-oct-2024-week-4/)_
145* All contributors on [Tangled](https://tangled.org/@zio.sh/atfile/pulls) and [GitHub](https://github.com/ziodotsh/atfile/pulls)
146* _(Forgot about you? [You know what to do](https://tangled.sh/@zio.sh/atfile/pulls/new))_
147
148---
149
150* **¹** You can bypass OS detection in one of two ways:
151 * Set `ATFILE_DISABLE_UNSUPPORTED_OS_WARN=1`<br />Be careful! There's a reason some OSes are not supported
152 * Set `ATFILE_FORCE_OS=<os>`<br />This overrides the OS detected. Possible values: `bsd`, `haiku`, `linux`, `linux-mingw`, `linux-musl`, `linux-termux`, `macos`, `serenity`, and `solaris`.
153* **²** musl-powered distros do not use GNU/glibc packages, and have problems currently
154 * Known musl distros: Alpine, Chimera, Dragora, Gentoo (musl), Morpheus, OpenWrt, postmarketOS, Sabotage, Void
155 * Bypassing OS detection (see ¹) will cause unintended behavior
156* **³** As long as you have Bash installed, running from another shell will not be problematic ([`#!/usr/bin/env bash`](https://tangled.sh/@zio.sh/atfile/blob/main/atfile.sh#L1) forces Bash)