PicoShare Documentation

To enable automatic data replication to a Litestream-compatible cloud storage location, provide the necessary Litestream environment variables. This allows PicoShare to restore data from the cloud if the container is restarted.

PORT=4001
PS_SHARED_SECRET="somesecretpass"
LITESTREAM_BUCKET=YOUR-LITESTREAM-BUCKET
LITESTREAM_ENDPOINT=YOUR-LITESTREAM-ENDPOINT
LITESTREAM_ACCESS_KEY_ID=YOUR-ACCESS-ID
LITESTREAM_SECRET_ACCESS_KEY=YOUR-SECRET-ACCESS-KEY

docker run \
  --publish "${PORT}:${PORT}/tcp" \
  --env "PORT=${PORT}" \
  --env "PS_SHARED_SECRET=${PS_SHARED_SECRET}" \
  --env "LITESTREAM_ACCESS_KEY_ID=${LITESTREAM_ACCESS_KEY_ID}" \
  --env "LITESTREAM_SECRET_ACCESS_KEY=${LITESTREAM_SECRET_ACCESS_KEY}" \
  --env "LITESTREAM_BUCKET=${LITESTREAM_BUCKET}" \
  --env "LITESTREAM_ENDPOINT=${LITESTREAM_ENDPOINT}" \
  --name picoshare \
  mtlynch/picoshare

Use the following docker-compose.yml configuration to manage PicoShare with Docker Compose. Note the use of the -db command flag to point to the mounted volume.

version: "3.2"
services:
  picoshare:
    image: mtlynch/picoshare
    environment:
      - PORT=4001
      - PS_SHARED_SECRET=dummypass # Change to any password
    ports:
      - 4001:4001
    command: -db /data/store.db
    volumes:
      - ./data:/data

Run PicoShare in a Docker container. You must mount a volume to store the SQLite database to ensure data persistence.

docker run \
  --env "PORT=4001" \
  --env "PS_SHARED_SECRET=somesecretpass" \
  --publish 4001:4001/tcp \
  --volume "${PWD}/data:/data" \
  --name picoshare \
  mtlynch/picoshare

To prevent data loss during server redeploys, you must either use a persistent volume or Litestream replication. To create a persistent volume on fly.io, create a volume and update your fly.toml to mount it at /data.

VOLUME_NAME='pico_data'
SIZE_IN_GB=3

fly volumes create "${VOLUME_NAME}" \
  --region "${REGION}" \
  --size "${SIZE_IN_GB}" && \
  {
  cat << EOF
[mounts]
  source="${VOLUME_NAME}"
  destination="/data"
EOF
  } >> fly.toml

Litestream can be used to replicate PicoShare's data to cloud storage. This requires setting environment variables for your cloud provider and configuring the bucket and endpoint in your fly.toml file.

1. Set Secrets: Use fly secrets set to securely store your cloud provider credentials.

2. Update fly.toml: Add LITESTREAM_BUCKET and LITESTREAM_ENDPOINT to the [env] section.

# Set secrets
LITESTREAM_ACCESS_KEY_ID=YOUR-ACCESS-ID
LITESTREAM_SECRET_ACCESS_KEY=YOUR-SECRET-ACCESS-KEY

fly secrets set \
  "LITESTREAM_ACCESS_KEY_ID=${LITESTREAM_ACCESS_KEY_ID}" \
  "LITESTREAM_SECRET_ACCESS_KEY=${LITESTREAM_SECRET_ACCESS_KEY}"

[env]
  LITESTREAM_BUCKET="YOUR-CLOUD-STORAGE-BUCKET"
  LITESTREAM_ENDPOINT="YOUR-CLOUD-STORAGE-ENDPOINT"

Once configuration and secrets are set, deploy the PicoShare Docker image to your fly.io app.

# Change this to the latest Docker image tag
PICOSHARE_IMAGE='mtlynch/picoshare:1.0.0'

fly deploy \
  --region="${REGION}" \
  --image "${PICOSHARE_IMAGE}" && \
  PICOSHARE_URL="https://${APP_NAME}.fly.dev/" && \
  echo "Your PicoShare instance is now ready at: ${PICOSHARE_URL}"

If you intend to contribute to PicoShare, follow these requirements based on your status:

• Individual Contributors: You must be the copyright owner of the contribution.
• Employees: If you created the contribution as part of your employment, you must have your employer approve the Agreement or have the employer sign the Entity version of the document.
• Multiple Authors: If you do not own the entire copyright of the work, all other authors of the contribution should also sign.

For questions or specific circumstances regarding the CLA, contact the maintainers at picoshare-cla@mtlynch.io.

To deploy PicoShare to fly.io, you must first create a fly app using a generated configuration. This process uses a remote script to create a fly.toml file for your specific app name.

Pre-requisites:

• A fly.io account with billing activated.
• The fly CLI installed and authenticated.

Steps:

1. Define a region (e.g., iad).
2. Generate a unique app name.
3. Run the configuration script and create the app via the fly CLI.

# You can change this to any region from https://fly.io/docs/reference/regions/
REGION='iad'

RANDOM_SUFFIX="$(head /dev/urandom | tr -dc 'a-z0-9' | head -c 6 ; echo '')"
APP_NAME="picoshare-${RANDOM_SUFFIX}"

curl -s -L https://raw.githubusercontent.com/mtlynch/picoshare/master/docs/deployment/fly-assets/make-fly-config | \
  bash /dev/stdin "${APP_NAME}"

fly apps create --name "${APP_NAME}"

To run PicoShare directly from the Go source code, set the PS_SHARED_SECRET and PORT environment variables and execute the main package.

PS_SHARED_SECRET=somesecretpass PORT=4001 \
  go run cmd/picoshare/main.go

Secure your PicoShare instance by setting a shared secret passphrase using fly secrets.

flyctl secrets set PS_SHARED_SECRET="somesecretpassphrase"

When files are deleted in PicoShare, the filesystem space is reserved for future uploads rather than being immediately returned to the OS. To manually shrink the SQLite database and reclaim space, follow these steps:

1. Shut down PicoShare.
2. Run the VACUUM command on the SQLite database using the path to your store.db.

Example command:

sqlite3 data/store.db 'VACUUM'