How to upload a large application to your onion service

How to upload a large application to your onion service

Uploading a whole application — hundreds of files, a few gigabytes — is the one job the browser tools are worst at. The portal's file manager and the SFTP client both have to move every byte over Tor, and your containers are deliberately throttled. The reliable recipe is: build one archive on your computer, upload that single file over SFTP, and unpack it on the server over SSH.

Why one archive instead of many files

• Tor latency is per connection, not per byte. Ten thousand small files means ten thousand round trips; one archive is one stream.
• Every container is limited to 1 MiB/s read and 1 MiB/s write (see "What happens when disk space limits are reached?"). No client can go faster, so the only thing you control is how efficiently the transfer uses that budget.
• An interrupted upload is resumable as a single file. With many small files you would be restarting hundreds of them.
• Unpacking happens inside the container, where a local copy is thousands of times faster than the network.

Budget your time at 1 MiB/s: 1 GB ≈ 17 minutes minimum, and realistically 30–60 minutes once Tor latency and the archive's own I/O are added. Compress first — a source archive usually shrinks to 20–40 % of its size, which cuts the transfer by the same factor.

Step 1 — Make the archive on your computer

Use tar.gz if you have the choice: tar is present in every container, while unzip is not guaranteed. A .zip works too — unzip is installed on the current images.

# from the directory that holds your application
tar czf app.tar.gz .

# or, if you prefer zip
zip -r app.zip .

Leave out what you can rebuild after the upload: node_modules, .git, local caches, vendor if you can run composer install on the server instead. Then check the size — and remember the free space of the service, which the portal shows on the File Access tab (the container itself reports it with php -r 'echo disk_free_space("/var/www/html");').

Step 2 — Upload it over SFTP

Connect as described in How to connect to your onion service over SFTP — protocol SFTP, port 22, the SFTP credentials from the File Access tab, through the SOCKS proxy of your Tor Browser (127.0.0.1:9150).

Drop the archive into www, which is the web root of the service. Two settings matter for a long transfer:

• File exists → Resume (FileZilla: Transfer → File exists, "Resume"). If the Tor circuit dies at 80 %, re-queueing the file continues instead of restarting.
• One transfer at a time, and do not close the laptop lid. The queue keeps going as long as the client runs.

Step 3 — Unpack it over SSH

Open the shell as described in How to connect to your onion service with SSH (port 2222, user www-user, your key). You land in /var/www/html, the web root — the same directory the SFTP client calls www. The shell is a restricted one: cd and > are refused, so give every command a path instead of changing directory:

pwd                     # /var/www/html
ls -lh app.tar.gz       # the file you just uploaded

tar xzf app.tar.gz      # extract in place
rm app.tar.gz           # free the space again

# for a zip upload
unzip -o app.zip
rm app.zip

To extract somewhere else, use -C rather than cd — this is the form that works in the restricted shell:

mkdir -p /var/www/html/shop
tar xzf /var/www/html/app.tar.gz -C /var/www/html/shop

Step 4 — Fix the permissions

Files you unpacked over SSH belong to www-user, while Apache serves the site as www-data. Read access is normally enough, but writable directories (uploads, caches, logs) need more:

chmod -R u+rwX,go+rX /var/www/html
chmod -R go+w /var/www/html/storage /var/www/html/uploads   # only if the app writes there

Step 5 — Check that it worked

Ask the container itself, then the browser:

ls -la                  # the expected directories/files
du -sh /var/www/html    # how much space the upload actually took

Then reload your onion address in the Tor Browser. A blank page or a 500 here is almost always a permissions problem or a missing entry file, not a broken upload.

Things that will bite you

• Uploading thousands of files instead of an archive: slower, and any interruption leaves you comparing directories by hand.
• Uploading a node_modules or vendor tree: usually several times the size of your code, for files you can rebuild on the server.
• Forgetting the space: the disk fills up mid-extract and tar stops with "Cannot write: No space left on device". Check the free space before, not after.
• Extracting into the wrong directory: the SFTP root lists www, logs and backup; only www is the web root.

Related articles

• How to connect to your onion service over SFTP
• How to connect to your onion service with SSH
• How to import a large MySQL dump into your onion service
• What happens when disk space limits are reached?