Store documents in Amazon S3

Use Amazon S3 when the Jiandu host already runs in AWS or your operating model includes S3 IAM, cost monitoring, lifecycle policy, and restore testing. Jiandu uses ordinary signed S3 operations; it does not create the bucket or manage its policy.

1. Create a dedicated namespace

Create a private general-purpose bucket in the region closest to the Jiandu host. Block public access. Either dedicate the bucket to this installation or choose a unique prefix such as jiandu/primary.

Bucket versioning can help recover from an accidental object change, but it is not a replacement for a Jiandu recovery backup. Review noncurrent-version retention and cost before enabling it. Do not apply Object Lock or a deny-delete policy to the live namespace: normal document lifecycle and crash recovery need copy and delete operations.

2. Grant only the required object scope

The following identity policy is a practical baseline for bucket household-archive and prefix jiandu/primary. Replace both values. Keep the bucket and object statements separate because S3 uses different resource forms for them.

jiandu-s3-policy.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListJianduNamespace",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:ListBucket",
        "s3:ListBucketMultipartUploads"
      ],
      "Resource": "arn:aws:s3:::household-archive",
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "jiandu/primary",
            "jiandu/primary/*"
          ]
        }
      }
    },
    {
      "Sid": "ManageJianduObjects",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::household-archive/jiandu/primary/*"
    }
  ]
}

Jiandu lists its publication ledger, reads and verifies objects, writes readiness and content objects, copies objects during guarded lifecycle operations, deletes objects, and uploads non-empty S3 blobs in 8 MiB multipart chunks. The multipart permissions prevent interrupted large uploads from becoming undeletable leftovers. If a stricter policy is desired, prove it with the full storage and recovery exercises rather than removing actions based only on a successful small readiness probe.

If the bucket enforces SSE-KMS with a customer-managed key, the role also needs the KMS permissions required by S3 for upload, read, copy, and multipart completion. Keep those permissions scoped to that key and validate a document larger than 8 MiB. Jiandu does not currently expose a setting to send a per-request KMS key ID; use a bucket default if customer-managed encryption is required.

See AWS's current S3 policy-action mapping and multipart upload permissions when adapting the policy.

3. Choose a credential source

Prefer temporary workload credentials over long-lived access keys. Jiandu's S3 adapter supports:

• static AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optional AWS_SESSION_TOKEN;
• web identity using AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN;
• ECS task credentials;
• EKS Pod Identity credentials; and
• EC2 instance credentials through IMDSv2.

The adapter does not load a named AWS_PROFILE or shared ~/.aws/credentials file. A setup that works with aws --profile household can still leave Jiandu without credentials. Inject supported environment values or attach a workload role to the actual service/container.

For Kubernetes with IRSA, for example, the platform supplies the token file and role variables; do not copy temporary values into the Jiandu configuration. For a local service that must use a static key, place the variables in the service manager's protected credential environment, not in jiandu.json, a Compose file committed to source control, or an interactive shell history.

4. Configure Jiandu

For native AWS S3, omit endpoint; Jiandu derives the regional AWS endpoint. Virtual-hosted-style requests are the conventional AWS form:

/etc/jiandu/jiandu.json

{
  "schema_version": 1,
  "data_directory": "/var/lib/jiandu",
  "storage": {
    "backend": "s3",
    "bucket": "household-archive",
    "region": "us-east-1",
    "prefix": "jiandu/primary",
    "work_root": "/var/lib/jiandu/storage-work",
    "allow_http": false,
    "virtual_hosted_style": true
  }
}

Why each non-default field exists:

Field	Purpose
bucket	Names the pre-created private bucket
region	Selects the signing region and regional S3 endpoint; it must match the bucket
prefix	Isolates this installation's object keys and narrows IAM scope
work_root	Keeps upload staging and processing snapshots on private local disk
allow_http: false	Makes an accidental plaintext endpoint invalid
virtual_hosted_style: true	Sends requests to the normal bucket-qualified AWS hostname

If you dedicated the entire bucket to Jiandu, prefix may be ""; keeping an explicit stable prefix is still useful for policy review and inventory.

5. Prepare local work storage

Remote blobs do not eliminate local writes:

sudo install -d -o jiandu -g jiandu -m 0700 /var/lib/jiandu
sudo install -d -o jiandu -g jiandu -m 0700 /var/lib/jiandu/storage-work
sudo -u jiandu jiandu --config /etc/jiandu/jiandu.json --check-config

The configuration check validates paths and fields without contacting AWS. Start Jiandu only after the workload credential is visible in the same runtime environment.

6. Verify permissions and behavior

Request readiness through the public origin:

curl --fail --silent https://documents.example.net/api/v1/health/ready

Then use a non-sensitive document larger than 8 MiB to exercise multipart upload, open and download it to exercise verified reads, and delete it to exercise lifecycle permissions. Finally, create and verify a recovery backup.

AWS-specific caveats

• S3 charges for requests, storage, retrieval, versioned data, replication, and sometimes network transfer. Readiness itself performs remote write/read/delete operations.
• A bucket policy, VPC endpoint policy, IAM permissions boundary, service control policy, or KMS key policy can deny a request even when the role policy appears correct.
• The region in Jiandu is a signing input. A redirect to another region is not a substitute for configuring the bucket's actual region.
• Virtual-hosted-style access requires DNS and TLS for the bucket-qualified AWS hostname. Bucket names containing dots can complicate TLS hostname matching in some custom endpoint designs.
• Lifecycle expiration must never delete current objects under the live prefix. Apply expiry to independently produced backups or explicitly understood noncurrent versions instead.