MyFSIO/templates/docs.html

{% extends "base.html" %}
{% block content %}
<section class="docs-hero p-4 p-md-5 rounded-4 mb-4">
  <div class="d-flex flex-column flex-lg-row justify-content-between gap-3">
    <div>
      <p class="text-uppercase fw-semibold small text-white-50 mb-2">Documentation</p>
      <h1 class="display-6 fw-semibold mb-2">Your guide to MyFSIO</h1>
      <p class="lead mb-0 text-light">Follow these steps to install, authenticate, master the console, and automate everything through the API.</p>
    </div>
    <div class="docs-callout text-light">
      <div class="small text-uppercase opacity-75">API base URL</div>
      <code class="fs-6 text-wrap">{{ api_base }}</code>
    </div>
  </div>
</section>
<div class="row g-4">
  <div class="col-12 d-xl-none">
    <div class="card shadow-sm docs-sidebar-mobile mb-0">
      <div class="card-body py-3">
        <div class="d-flex align-items-center justify-content-between mb-2">
          <h3 class="h6 text-uppercase text-muted mb-0">On this page</h3>
          <button class="btn btn-sm btn-outline-secondary" type="button" data-bs-toggle="collapse" data-bs-target="#mobileDocsToc" aria-expanded="false" aria-controls="mobileDocsToc">
            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 16 16">
              <path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/>
            </svg>
          </button>
        </div>
        <div class="collapse" id="mobileDocsToc">
          <ul class="list-unstyled docs-toc mb-0 small">
            <li><a href="#setup">Set up &amp; run</a></li>
            <li><a href="#background">Running in background</a></li>
            <li><a href="#auth">Authentication &amp; IAM</a></li>
            <li><a href="#console">Console tour</a></li>
            <li><a href="#automation">Automation / CLI</a></li>
            <li><a href="#api">REST endpoints</a></li>
            <li><a href="#examples">API Examples</a></li>
            <li><a href="#replication">Site Replication</a></li>
            <li><a href="#versioning">Object Versioning</a></li>
            <li><a href="#quotas">Bucket Quotas</a></li>
            <li><a href="#encryption">Encryption</a></li>
            <li><a href="#lifecycle">Lifecycle Rules</a></li>
            <li><a href="#metrics">Metrics History</a></li>
            <li><a href="#troubleshooting">Troubleshooting</a></li>
          </ul>
        </div>
      </div>
    </div>
  </div>
  <div class="col-xl-8">
    <article id="setup" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">01</span>
          <h2 class="h4 mb-0">Set up &amp; run locally</h2>
        </div>
        <p class="text-muted">Prepare a virtual environment, install dependencies, and launch both servers for a complete console + API experience.</p>
        <ol class="docs-steps">
          <li>Install Python 3.11+ plus system build tools.</li>
          <li>Create a virtual environment and install <code>requirements.txt</code>.</li>
          <li>Start the services with <code>python run.py</code>.</li>
        </ol>
<pre class="mb-3"><code class="language-bash">python -m venv .venv
. .venv/Scripts/activate      # PowerShell: .\\.venv\\Scripts\\Activate.ps1
pip install -r requirements.txt

# Run both API and UI (Development)
python run.py

# Run in Production (Waitress server)
python run.py --prod

# Or run individually
python run.py --mode api
python run.py --mode ui
</code></pre>
        <h3 class="h6 mt-4 mb-2">Configuration</h3>
        <p class="text-muted small">Configuration defaults live in <code>app/config.py</code>. You can override them using environment variables. This is critical for production deployments behind proxies.</p>
        <div class="table-responsive">
          <table class="table table-sm table-bordered small mb-0">
            <thead class="table-light">
              <tr>
                <th style="min-width: 180px;">Variable</th>
                <th style="min-width: 120px;">Default</th>
                <th class="text-wrap" style="min-width: 250px;">Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><code>API_BASE_URL</code></td>
                <td><code>None</code></td>
                <td>The public URL of the API. <strong>Required</strong> if running behind a proxy. Ensures presigned URLs are generated correctly.</td>
              </tr>
              <tr>
                <td><code>STORAGE_ROOT</code></td>
                <td><code>./data</code></td>
                <td>Directory for buckets and objects.</td>
              </tr>
              <tr>
                <td><code>MAX_UPLOAD_SIZE</code></td>
                <td><code>1 GB</code></td>
                <td>Max request body size in bytes.</td>
              </tr>
              <tr>
                <td><code>SECRET_KEY</code></td>
                <td>(Auto-generated)</td>
                <td>Flask session key. Auto-generates if not set. <strong>Set explicitly in production.</strong></td>
              </tr>
              <tr>
                <td><code>APP_HOST</code></td>
                <td><code>0.0.0.0</code></td>
                <td>Bind interface.</td>
              </tr>
              <tr>
                <td><code>APP_PORT</code></td>
                <td><code>5000</code></td>
                <td>Listen port (UI uses 5100).</td>
              </tr>
              <tr class="table-secondary">
                <td colspan="3" class="fw-semibold">CORS Settings</td>
              </tr>
              <tr>
                <td><code>CORS_ORIGINS</code></td>
                <td><code>*</code></td>
                <td>Allowed origins. <strong>Restrict in production.</strong></td>
              </tr>
              <tr>
                <td><code>CORS_METHODS</code></td>
                <td><code>GET,PUT,POST,DELETE,OPTIONS,HEAD</code></td>
                <td>Allowed HTTP methods.</td>
              </tr>
              <tr>
                <td><code>CORS_ALLOW_HEADERS</code></td>
                <td><code>*</code></td>
                <td>Allowed request headers.</td>
              </tr>
              <tr>
                <td><code>CORS_EXPOSE_HEADERS</code></td>
                <td><code>*</code></td>
                <td>Response headers visible to browsers (e.g., <code>ETag</code>).</td>
              </tr>
              <tr class="table-secondary">
                <td colspan="3" class="fw-semibold">Security Settings</td>
              </tr>
              <tr>
                <td><code>AUTH_MAX_ATTEMPTS</code></td>
                <td><code>5</code></td>
                <td>Failed login attempts before lockout.</td>
              </tr>
              <tr>
                <td><code>AUTH_LOCKOUT_MINUTES</code></td>
                <td><code>15</code></td>
                <td>Lockout duration after max failed attempts.</td>
              </tr>
              <tr>
                <td><code>RATE_LIMIT_DEFAULT</code></td>
                <td><code>200 per minute</code></td>
                <td>Default API rate limit.</td>
              </tr>
              <tr class="table-secondary">
                <td colspan="3" class="fw-semibold">Encryption Settings</td>
              </tr>
              <tr>
                <td><code>ENCRYPTION_ENABLED</code></td>
                <td><code>false</code></td>
                <td>Enable server-side encryption support.</td>
              </tr>
              <tr>
                <td><code>KMS_ENABLED</code></td>
                <td><code>false</code></td>
                <td>Enable KMS key management for encryption.</td>
              </tr>
              <tr class="table-secondary">
                <td colspan="3" class="fw-semibold">Logging Settings</td>
              </tr>
              <tr>
                <td><code>LOG_LEVEL</code></td>
                <td><code>INFO</code></td>
                <td>Log verbosity: DEBUG, INFO, WARNING, ERROR.</td>
              </tr>
              <tr>
                <td><code>LOG_TO_FILE</code></td>
                <td><code>true</code></td>
                <td>Enable file logging.</td>
              </tr>
              <tr class="table-secondary">
                <td colspan="3" class="fw-semibold">Metrics History Settings</td>
              </tr>
              <tr>
                <td><code>METRICS_HISTORY_ENABLED</code></td>
                <td><code>false</code></td>
                <td>Enable metrics history recording and charts (opt-in).</td>
              </tr>
              <tr>
                <td><code>METRICS_HISTORY_RETENTION_HOURS</code></td>
                <td><code>24</code></td>
                <td>How long to retain metrics history data.</td>
              </tr>
              <tr>
                <td><code>METRICS_HISTORY_INTERVAL_MINUTES</code></td>
                <td><code>5</code></td>
                <td>Interval between history snapshots.</td>
              </tr>
            </tbody>
          </table>
        </div>
        <div class="alert alert-warning mt-3 mb-0 small">
          <strong>Production Checklist:</strong> Set <code>SECRET_KEY</code>, restrict <code>CORS_ORIGINS</code>, configure <code>API_BASE_URL</code>, enable HTTPS via reverse proxy, and use <code>--prod</code> flag.
        </div>
      </div>
    </article>
    <article id="background" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">02</span>
          <h2 class="h4 mb-0">Running in background</h2>
        </div>
        <p class="text-muted">For production or server deployments, run MyFSIO as a background service so it persists after you close the terminal.</p>
        
        <h3 class="h6 text-uppercase text-muted mt-4">Quick Start (nohup)</h3>
        <p class="text-muted small">Simplest way to run in background—survives terminal close:</p>
<pre class="mb-3"><code class="language-bash"># Using Python
nohup python run.py --prod > /dev/null 2>&1 &

# Using compiled binary
nohup ./myfsio > /dev/null 2>&1 &

# Check if running
ps aux | grep myfsio</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">Screen / Tmux</h3>
        <p class="text-muted small">Attach/detach from a persistent session:</p>
<pre class="mb-3"><code class="language-bash"># Start in a detached screen session
screen -dmS myfsio ./myfsio

# Attach to view logs
screen -r myfsio

# Detach: press Ctrl+A, then D</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">Systemd (Recommended for Production)</h3>
        <p class="text-muted small">Create <code>/etc/systemd/system/myfsio.service</code>:</p>
<pre class="mb-3"><code class="language-ini">[Unit]
Description=MyFSIO S3-Compatible Storage
After=network.target

[Service]
Type=simple
User=myfsio
WorkingDirectory=/opt/myfsio
ExecStart=/opt/myfsio/myfsio
Restart=on-failure
RestartSec=5
Environment=STORAGE_ROOT=/var/lib/myfsio
Environment=API_BASE_URL=https://s3.example.com

[Install]
WantedBy=multi-user.target</code></pre>
        <p class="text-muted small">Then enable and start:</p>
<pre class="mb-0"><code class="language-bash">sudo systemctl daemon-reload
sudo systemctl enable myfsio
sudo systemctl start myfsio

# Check status
sudo systemctl status myfsio
sudo journalctl -u myfsio -f   # View logs</code></pre>
      </div>
    </article>
    <article id="auth" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">03</span>
          <h2 class="h4 mb-0">Authenticate &amp; manage IAM</h2>
        </div>
        <p class="text-muted">MyFSIO seeds <code>data/.myfsio.sys/config/iam.json</code> with <code>localadmin/localadmin</code>. Sign in once, rotate it, then grant least-privilege access to teammates and tools.</p>
        <div class="docs-highlight mb-3">
          <ol class="mb-0">
            <li>Visit <code>/ui/login</code>, enter the bootstrap credentials, and rotate them immediately from the IAM page.</li>
            <li>Create additional users with descriptive display names and AWS-style inline policies (for example <code>{"bucket": "*", "actions": ["list", "read"]}</code>).</li>
            <li>Rotate secrets when sharing with CI jobs—new secrets display once and persist to <code>data/.myfsio.sys/config/iam.json</code>.</li>
            <li>Bucket policies layer on top of IAM. Apply Private/Public presets or paste custom JSON; changes reload instantly.</li>
          </ol>
        </div>
        <p class="mb-0 text-muted">All API calls require <code>X-Access-Key</code> and <code>X-Secret-Key</code> headers. The UI stores them in the Flask session after you log in.</p>
      </div>
    </article>
    <article id="console" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">04</span>
          <h2 class="h4 mb-0">Use the console effectively</h2>
        </div>
        <p class="text-muted">Each workspace models an S3 workflow so you can administer buckets end-to-end.</p>
        <div class="docs-pill-list">
          <div>
            <h3 class="h6 text-uppercase text-muted">Buckets</h3>
            <ul>
              <li>Create/delete buckets from the overview. Badges reveal IAM-only, public-read, or custom-policy states.</li>
              <li>Summary stats show live object counts and total capacity; click through for inventories.</li>
            </ul>
          </div>
          <div>
            <h3 class="h6 text-uppercase text-muted">Uploads</h3>
            <ul>
              <li>Drag and drop folders or files into the upload modal. Objects above 16&nbsp;MB switch to multipart automatically.</li>
              <li>Progress rows highlight retries, throughput, and completion even if you close the modal.</li>
            </ul>
          </div>
          <div>
            <h3 class="h6 text-uppercase text-muted">Object browser</h3>
            <ul>
              <li>Navigate folder hierarchies using breadcrumbs. Objects with <code>/</code> in keys display as folders.</li>
              <li>Infinite scroll loads more objects automatically. Choose batch size (50–250) from the footer dropdown.</li>
              <li>Bulk select objects for multi-delete or multi-download. Filter by name using the search box.</li>
              <li>If loading fails, click <strong>Retry</strong> to attempt again—no page refresh needed.</li>
            </ul>
          </div>
          <div>
            <h3 class="h6 text-uppercase text-muted">Object details</h3>
            <ul>
              <li>Selecting an object opens the preview card with metadata, inline viewers, presign generator, and version history.</li>
              <li>Trigger downloads, deletes, restores, or metadata refreshes without leaving the panel.</li>
            </ul>
          </div>
          <div>
            <h3 class="h6 text-uppercase text-muted">Policies &amp; versioning</h3>
            <ul>
              <li>Toggle versioning (requires write access). Archived-only keys are flagged so you can restore them quickly.</li>
              <li>The policy editor saves drafts, ships with presets, and hot-reloads <code>data/.myfsio.sys/config/bucket_policies.json</code>.</li>
            </ul>
          </div>
        </div>
      </div>
    </article>
    <article id="automation" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">05</span>
          <h2 class="h4 mb-0">Automate with CLI &amp; tools</h2>
        </div>
        <p class="text-muted">Point standard S3 clients at {{ api_base }} and reuse the same IAM credentials.</p>
        <div class="mb-4">
          <h3 class="h6 text-uppercase text-muted">AWS CLI</h3>
<pre class="mb-3"><code class="language-bash">aws configure set aws_access_key_id &lt;access_key&gt;
aws configure set aws_secret_access_key &lt;secret_key&gt;
aws configure set default.region us-east-1

aws --endpoint-url {{ api_base }} s3 ls
aws --endpoint-url {{ api_base }} s3api create-bucket --bucket demo
aws --endpoint-url {{ api_base }} s3 cp ./sample.txt s3://demo/sample.txt
</code></pre>
        </div>
        <div class="mb-4">
          <h3 class="h6 text-uppercase text-muted">s3cmd</h3>
<pre class="mb-3"><code class="language-bash">cat &gt; ~/.s3cfg-myfsio &lt;&lt;'EOF'
host_base = {{ api_host }}
host_bucket = %(bucket)s.{{ api_host }}
access_key = &lt;access_key&gt;
secret_key = &lt;secret_key&gt;
use_https = False
signature_v2 = False
EOF

s3cmd --config ~/.s3cfg-myfsio ls
s3cmd --config ~/.s3cfg-myfsio put notes.txt s3://demo/notes.txt
</code></pre>
        </div>
        <div>
          <h3 class="h6 text-uppercase text-muted">curl / HTTPie</h3>
<pre class="mb-0"><code class="language-bash">curl {{ api_base }}/ \
  -H "X-Access-Key: &lt;access_key&gt;" \
  -H "X-Secret-Key: &lt;secret_key&gt;"

curl -X PUT {{ api_base }}/demo/notes.txt \
  -H "X-Access-Key: &lt;access_key&gt;" \
  -H "X-Secret-Key: &lt;secret_key&gt;" \
  --data-binary @notes.txt

curl -X POST {{ api_base }}/presign/demo/notes.txt \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;access_key&gt;" \
  -H "X-Secret-Key: &lt;secret_key&gt;" \
  -d '{"method":"GET", "expires_in": 900}'
</code></pre>
        </div>
      </div>
    </article>
    <article id="api" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">06</span>
          <h2 class="h4 mb-0">Key REST endpoints</h2>
        </div>
        <div class="table-responsive">
          <table class="table table-sm table-borderless align-middle docs-table mb-0">
            <thead>
              <tr>
                <th scope="col">Method</th>
                <th scope="col">Path</th>
                <th scope="col">Purpose</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>GET</td>
                <td><code>/</code></td>
                <td>List buckets accessible to the caller.</td>
              </tr>
              <tr>
                <td>PUT</td>
                <td><code>/&lt;bucket&gt;</code></td>
                <td>Create a bucket.</td>
              </tr>
              <tr>
                <td>DELETE</td>
                <td><code>/&lt;bucket&gt;</code></td>
                <td>Delete a bucket (must be empty).</td>
              </tr>
              <tr>
                <td>GET</td>
                <td><code>/&lt;bucket&gt;</code></td>
                <td>List objects (supports <code>prefix</code> / <code>max-keys</code> queries).</td>
              </tr>
              <tr>
                <td>PUT</td>
                <td><code>/&lt;bucket&gt;/&lt;key&gt;</code></td>
                <td>Upload or overwrite an object; UI helper handles multipart flows.</td>
              </tr>
              <tr>
                <td>GET</td>
                <td><code>/&lt;bucket&gt;/&lt;key&gt;</code></td>
                <td>Download an object (UI adds <code>?download=1</code> to force attachment).</td>
              </tr>
              <tr>
                <td>DELETE</td>
                <td><code>/&lt;bucket&gt;/&lt;key&gt;</code></td>
                <td>Delete an object.</td>
              </tr>
              <tr>
                <td>GET/PUT/DELETE</td>
                <td><code>/bucket-policy/&lt;bucket&gt;</code></td>
                <td>Fetch, upsert, or remove a bucket policy.</td>
              </tr>
              <tr>
                <td>POST</td>
                <td><code>/presign/&lt;bucket&gt;/&lt;key&gt;</code></td>
                <td>Generate SigV4 URLs for GET/PUT/DELETE with custom expiry.</td>
              </tr>
            </tbody>
          </table>
        </div>
        <p class="small text-muted mt-3 mb-0">All responses include <code>X-Request-Id</code> for tracing. Logs land in <code>logs/api.log</code> and <code>logs/ui.log</code>.</p>
      </div>
    </article>
    <article id="examples" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">07</span>
          <h2 class="h4 mb-0">API Examples</h2>
        </div>
        <p class="text-muted">Common operations using popular SDKs and tools.</p>

        <h3 class="h6 text-uppercase text-muted mt-4">Python (boto3)</h3>
<pre class="mb-4"><code class="language-python">import boto3

s3 = boto3.client(
    's3',
    endpoint_url='{{ api_base }}',
    aws_access_key_id='&lt;access_key&gt;',
    aws_secret_access_key='&lt;secret_key&gt;'
)

# List buckets
buckets = s3.list_buckets()['Buckets']

# Create bucket
s3.create_bucket(Bucket='mybucket')

# Upload file
s3.upload_file('local.txt', 'mybucket', 'remote.txt')

# Download file
s3.download_file('mybucket', 'remote.txt', 'downloaded.txt')

# Generate presigned URL (valid 1 hour)
url = s3.generate_presigned_url(
    'get_object',
    Params={'Bucket': 'mybucket', 'Key': 'remote.txt'},
    ExpiresIn=3600
)</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">JavaScript (AWS SDK v3)</h3>
<pre class="mb-4"><code class="language-javascript">import { S3Client, ListBucketsCommand, PutObjectCommand } from '@aws-sdk/client-s3';

const s3 = new S3Client({
  endpoint: '{{ api_base }}',
  region: 'us-east-1',
  credentials: {
    accessKeyId: '&lt;access_key&gt;',
    secretAccessKey: '&lt;secret_key&gt;'
  },
  forcePathStyle: true  // Required for S3-compatible services
});

// List buckets
const { Buckets } = await s3.send(new ListBucketsCommand({}));

// Upload object
await s3.send(new PutObjectCommand({
  Bucket: 'mybucket',
  Key: 'hello.txt',
  Body: 'Hello, World!'
}));</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">Multipart Upload (Python)</h3>
<pre class="mb-4"><code class="language-python">import boto3

s3 = boto3.client('s3', endpoint_url='{{ api_base }}')

# Initiate
response = s3.create_multipart_upload(Bucket='mybucket', Key='large.bin')
upload_id = response['UploadId']

# Upload parts (minimum 5MB each, except last part)
parts = []
chunks = [b'chunk1...', b'chunk2...']
for part_number, chunk in enumerate(chunks, start=1):
    response = s3.upload_part(
        Bucket='mybucket',
        Key='large.bin',
        PartNumber=part_number,
        UploadId=upload_id,
        Body=chunk
    )
    parts.append({'PartNumber': part_number, 'ETag': response['ETag']})

# Complete
s3.complete_multipart_upload(
    Bucket='mybucket',
    Key='large.bin',
    UploadId=upload_id,
    MultipartUpload={'Parts': parts}
)</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">Presigned URLs for Sharing</h3>
<pre class="mb-0"><code class="language-bash"># Generate a download link valid for 15 minutes
curl -X POST "{{ api_base }}/presign/mybucket/photo.jpg" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"method": "GET", "expires_in": 900}'

# Generate an upload link (PUT) valid for 1 hour
curl -X POST "{{ api_base }}/presign/mybucket/upload.bin" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"method": "PUT", "expires_in": 3600}'</code></pre>
      </div>
    </article>
    <article id="replication" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">08</span>
          <h2 class="h4 mb-0">Site Replication</h2>
        </div>
        <p class="text-muted">Automatically copy new objects to another MyFSIO instance or S3-compatible service for backup or disaster recovery.</p>
        
        <h3 class="h6 text-uppercase text-muted mt-4">Setup Guide</h3>
        <ol class="docs-steps mb-3">
            <li>
                <strong>Prepare Target:</strong> On the destination server, create a bucket (e.g., <code>backup-bucket</code>) and an IAM user with write permissions.
            </li>
            <li>
                <strong>Connect Source:</strong> On this server, go to <a href="{{ url_for('ui.connections_dashboard') }}">Connections</a> and add the target's API URL and credentials.
            </li>
            <li>
                <strong>Enable Rule:</strong> Go to the source bucket's <strong>Replication</strong> tab, select the connection, and enter the target bucket name.
            </li>
        </ol>

        <div class="alert alert-light border mb-3 overflow-hidden">
            <div class="d-flex flex-column flex-sm-row gap-2 mb-2">
                <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-terminal text-muted mt-1 flex-shrink-0 d-none d-sm-block" viewBox="0 0 16 16">
                  <path d="M6 9a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3A.5.5 0 0 1 6 9zM3.854 4.146a.5.5 0 1 0-.708.708L4.793 6.5 3.146 8.146a.5.5 0 1 0 .708.708l2-2a.5.5 0 0 0 0-.708l-2-2z"/>
                  <path d="M2 1a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V3a2 2 0 0 0-2-2H2zm12 1a1 1 0 0 1 1 1v10a1 1 0 0 1-1 1H2a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1h12z"/>
                </svg>
                <div class="flex-grow-1 min-width-0">
                    <strong>Headless Target Setup</strong>
                    <p class="small text-muted mb-2">If your target server has no UI, create a <code>setup_target.py</code> script to bootstrap credentials:</p>
<pre class="mb-0 overflow-auto" style="max-width: 100%;"><code class="language-python"># setup_target.py
from pathlib import Path
from app.iam import IamService
from app.storage import ObjectStorage

# Initialize services (paths match default config)
data_dir = Path("data")
iam = IamService(data_dir / ".myfsio.sys" / "config" / "iam.json")
storage = ObjectStorage(data_dir)

# 1. Create the bucket
bucket_name = "backup-bucket"
try:
    storage.create_bucket(bucket_name)
    print(f"Bucket '{bucket_name}' created.")
except Exception as e:
    print(f"Bucket creation skipped: {e}")

# 2. Create the user
try:
    creds = iam.create_user(
        display_name="Replication User",
        policies=[{"bucket": bucket_name, "actions": ["write", "read", "list"]}]
    )
    print("\n--- CREDENTIALS GENERATED ---")
    print(f"Access Key: {creds['access_key']}")
    print(f"Secret Key: {creds['secret_key']}")
    print("-----------------------------")
except Exception as e:
    print(f"User creation failed: {e}")</code></pre>
                    <p class="small text-muted mt-2 mb-0">Save and run: <code>python setup_target.py</code></p>
                </div>
            </div>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">Bidirectional Replication (Active-Active)</h3>
        <p class="small text-muted">To set up two-way replication (Server A ↔ Server B):</p>
        <ol class="docs-steps mb-3">
            <li>Follow the steps above to replicate <strong>A → B</strong>.</li>
            <li>Repeat the process on Server B to replicate <strong>B → A</strong> (create a connection to A, enable rule).</li>
        </ol>
        <p class="small text-muted mb-3">
            <strong>Loop Prevention:</strong> The system automatically detects replication traffic using a custom User-Agent (<code>S3ReplicationAgent</code>). This prevents infinite loops where an object replicated from A to B is immediately replicated back to A.
            <br>
            <strong>Deletes:</strong> Deleting an object on one server will propagate the deletion to the other server.
        </p>

        <h3 class="h6 text-uppercase text-muted mt-4">Error Handling &amp; Rate Limits</h3>
        <p class="small text-muted mb-3">The replication system handles transient failures automatically:</p>
        <div class="table-responsive mb-3">
          <table class="table table-sm table-bordered small">
            <thead class="table-light">
              <tr>
                <th>Behavior</th>
                <th>Details</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><strong>Retry Logic</strong></td>
                <td>boto3 automatically handles 429 (rate limit) errors using exponential backoff with <code>max_attempts=2</code></td>
              </tr>
              <tr>
                <td><strong>Concurrency</strong></td>
                <td>Uses a ThreadPoolExecutor with 4 parallel workers for replication tasks</td>
              </tr>
              <tr>
                <td><strong>Timeouts</strong></td>
                <td>Connect: 5s, Read: 30s. Large files use streaming transfers</td>
              </tr>
            </tbody>
          </table>
        </div>
        <div class="alert alert-warning border mb-0">
          <div class="d-flex gap-2">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-exclamation-triangle text-warning mt-1 flex-shrink-0" viewBox="0 0 16 16">
              <path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/>
              <path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/>
            </svg>
            <div>
              <strong>Large File Counts:</strong> When replicating buckets with many objects, the target server's rate limits may cause delays. There is no built-in pause mechanism. Consider increasing <code>RATE_LIMIT_DEFAULT</code> on the target server during bulk replication operations.
            </div>
          </div>
        </div>
      </div>
    </article>
    <article id="versioning" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">09</span>
          <h2 class="h4 mb-0">Object Versioning</h2>
        </div>
        <p class="text-muted">Keep multiple versions of objects to protect against accidental deletions and overwrites. Restore previous versions at any time.</p>

        <h3 class="h6 text-uppercase text-muted mt-4">Enabling Versioning</h3>
        <ol class="docs-steps mb-3">
          <li>Navigate to your bucket's <strong>Properties</strong> tab.</li>
          <li>Find the <strong>Versioning</strong> card and click <strong>Enable</strong>.</li>
          <li>All subsequent uploads will create new versions instead of overwriting.</li>
        </ol>

        <h3 class="h6 text-uppercase text-muted mt-4">Version Operations</h3>
        <div class="table-responsive mb-3">
          <table class="table table-sm table-bordered small">
            <thead class="table-light">
              <tr>
                <th>Operation</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><strong>View Versions</strong></td>
                <td>Click the version icon on any object to see all historical versions with timestamps and sizes.</td>
              </tr>
              <tr>
                <td><strong>Restore Version</strong></td>
                <td>Click <strong>Restore</strong> on any version to make it the current version (creates a copy).</td>
              </tr>
              <tr>
                <td><strong>Delete Current</strong></td>
                <td>Deleting an object archives it. Previous versions remain accessible.</td>
              </tr>
              <tr>
                <td><strong>Purge All</strong></td>
                <td>Permanently delete an object and all its versions. This cannot be undone.</td>
              </tr>
            </tbody>
          </table>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">Archived Objects</h3>
        <p class="small text-muted mb-3">When you delete a versioned object, it becomes "archived" - the current version is removed but historical versions remain. The <strong>Archived</strong> tab shows these objects so you can restore them.</p>

        <h3 class="h6 text-uppercase text-muted mt-4">API Usage</h3>
<pre class="mb-3"><code class="language-bash"># Enable versioning
curl -X PUT "{{ api_base }}/&lt;bucket&gt;?versioning" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"Status": "Enabled"}'

# Get versioning status
curl "{{ api_base }}/&lt;bucket&gt;?versioning" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# List object versions
curl "{{ api_base }}/&lt;bucket&gt;?versions" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Get specific version
curl "{{ api_base }}/&lt;bucket&gt;/&lt;key&gt;?versionId=&lt;version-id&gt;" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"</code></pre>

        <div class="alert alert-light border mb-0">
          <div class="d-flex gap-2">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-info-circle text-muted mt-1" viewBox="0 0 16 16">
              <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>
              <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
            </svg>
            <div>
              <strong>Storage Impact:</strong> Each version consumes storage. Enable quotas to limit total bucket size including all versions.
            </div>
          </div>
        </div>
      </div>
    </article>
    <article id="quotas" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">10</span>
          <h2 class="h4 mb-0">Bucket Quotas</h2>
        </div>
        <p class="text-muted">Limit how much data a bucket can hold using storage quotas. Quotas are enforced on uploads and multipart completions.</p>
        
        <h3 class="h6 text-uppercase text-muted mt-4">Quota Types</h3>
        <div class="table-responsive mb-3">
          <table class="table table-sm table-bordered small">
            <thead class="table-light">
              <tr>
                <th>Limit</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><strong>Max Size (MB)</strong></td>
                <td>Maximum total storage in megabytes (includes current objects + archived versions)</td>
              </tr>
              <tr>
                <td><strong>Max Objects</strong></td>
                <td>Maximum number of objects (includes current objects + archived versions)</td>
              </tr>
            </tbody>
          </table>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">Managing Quotas (Admin Only)</h3>
        <p class="small text-muted">Quota management is restricted to administrators (users with <code>iam:*</code> permissions).</p>
        <ol class="docs-steps mb-3">
          <li>Navigate to your bucket → <strong>Properties</strong> tab → <strong>Storage Quota</strong> card.</li>
          <li>Enter limits: <strong>Max Size (MB)</strong> and/or <strong>Max Objects</strong>. Leave empty for unlimited.</li>
          <li>Click <strong>Update Quota</strong> to save, or <strong>Remove Quota</strong> to clear limits.</li>
        </ol>

        <h3 class="h6 text-uppercase text-muted mt-4">API Usage</h3>
<pre class="mb-3"><code class="language-bash"># Set quota (max 100MB, max 1000 objects)
curl -X PUT "{{ api_base }}/bucket/&lt;bucket&gt;?quota" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"max_bytes": 104857600, "max_objects": 1000}'

# Get current quota
curl "{{ api_base }}/bucket/&lt;bucket&gt;?quota" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Remove quota
curl -X PUT "{{ api_base }}/bucket/&lt;bucket&gt;?quota" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"max_bytes": null, "max_objects": null}'</code></pre>

        <div class="alert alert-light border mb-0">
          <div class="d-flex gap-2">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-info-circle text-muted mt-1" viewBox="0 0 16 16">
              <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>
              <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
            </svg>
            <div>
              <strong>Version Counting:</strong> When versioning is enabled, archived versions count toward the quota. The quota is checked against total storage, not just current objects.
            </div>
          </div>
        </div>
      </div>
    </article>
    <article id="encryption" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">11</span>
          <h2 class="h4 mb-0">Encryption</h2>
        </div>
        <p class="text-muted">Protect data at rest with server-side encryption using AES-256-GCM. Objects are encrypted before being written to disk and decrypted transparently on read.</p>
        
        <h3 class="h6 text-uppercase text-muted mt-4">Encryption Types</h3>
        <div class="table-responsive mb-3">
          <table class="table table-sm table-bordered small">
            <thead class="table-light">
              <tr>
                <th>Type</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><strong>AES-256 (SSE-S3)</strong></td>
                <td>Server-managed encryption using a local master key</td>
              </tr>
              <tr>
                <td><strong>KMS (SSE-KMS)</strong></td>
                <td>Encryption using customer-managed keys via the built-in KMS</td>
              </tr>
            </tbody>
          </table>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">Enabling Encryption</h3>
        <ol class="docs-steps mb-3">
          <li>
            <strong>Set environment variables:</strong>
<pre class="mb-2"><code class="language-bash"># PowerShell
$env:ENCRYPTION_ENABLED = "true"
$env:KMS_ENABLED = "true"  # Optional
python run.py

# Bash
export ENCRYPTION_ENABLED=true
export KMS_ENABLED=true
python run.py</code></pre>
          </li>
          <li>
            <strong>Configure bucket encryption:</strong> Navigate to your bucket → <strong>Properties</strong> tab → <strong>Default Encryption</strong> card → Click <strong>Enable Encryption</strong>.
          </li>
          <li>
            <strong>Choose algorithm:</strong> Select <strong>AES-256</strong> for server-managed keys or <strong>aws:kms</strong> to use a KMS-managed key.
          </li>
        </ol>

        <div class="alert alert-warning border-warning bg-warning-subtle mb-3">
          <div class="d-flex gap-2">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-exclamation-triangle mt-1" viewBox="0 0 16 16">
              <path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.146.146 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.163.163 0 0 1-.054.06.116.116 0 0 1-.066.017H1.146a.115.115 0 0 1-.066-.017.163.163 0 0 1-.054-.06.176.176 0 0 1 .002-.183L7.884 2.073a.147.147 0 0 1 .054-.057zm1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566z"/>
              <path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0zM7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995z"/>
            </svg>
            <div>
              <strong>Important:</strong> Only <em>new uploads</em> after enabling encryption will be encrypted. Existing objects remain unencrypted.
            </div>
          </div>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">KMS Key Management</h3>
        <p class="small text-muted">When <code>KMS_ENABLED=true</code>, manage encryption keys via the API:</p>
<pre class="mb-3"><code class="language-bash"># Create a new KMS key
curl -X POST {{ api_base }}/kms/keys \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"alias": "my-key", "description": "Production key"}'

# List all keys
curl {{ api_base }}/kms/keys \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Rotate a key (creates new key material)
curl -X POST {{ api_base }}/kms/keys/{key-id}/rotate \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Disable/Enable a key
curl -X POST {{ api_base }}/kms/keys/{key-id}/disable \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Schedule key deletion (30-day waiting period)
curl -X DELETE "{{ api_base }}/kms/keys/{key-id}?waiting_period_days=30" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">How It Works</h3>
        <p class="small text-muted mb-0">
          <strong>Envelope Encryption:</strong> Each object is encrypted with a unique Data Encryption Key (DEK). The DEK is then encrypted (wrapped) by the master key or KMS key and stored alongside the ciphertext. On read, the DEK is unwrapped and used to decrypt the object transparently.
        </p>
      </div>
    </article>
    <article id="lifecycle" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">12</span>
          <h2 class="h4 mb-0">Lifecycle Rules</h2>
        </div>
        <p class="text-muted">Automatically delete expired objects, clean up old versions, and abort incomplete multipart uploads using time-based lifecycle rules.</p>

        <h3 class="h6 text-uppercase text-muted mt-4">How It Works</h3>
        <p class="small text-muted mb-3">
          Lifecycle rules run on a background timer (Python <code>threading.Timer</code>), not a system cronjob. The enforcement cycle triggers every <strong>3600 seconds (1 hour)</strong> by default. Each cycle scans all buckets with lifecycle configurations and applies matching rules.
        </p>

        <h3 class="h6 text-uppercase text-muted mt-4">Expiration Types</h3>
        <div class="table-responsive mb-3">
          <table class="table table-sm table-bordered small">
            <thead class="table-light">
              <tr>
                <th>Type</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><strong>Expiration (Days)</strong></td>
                <td>Delete current objects older than N days from their last modification</td>
              </tr>
              <tr>
                <td><strong>Expiration (Date)</strong></td>
                <td>Delete current objects after a specific date (ISO 8601 format)</td>
              </tr>
              <tr>
                <td><strong>NoncurrentVersionExpiration</strong></td>
                <td>Delete non-current (archived) versions older than N days from when they became non-current</td>
              </tr>
              <tr>
                <td><strong>AbortIncompleteMultipartUpload</strong></td>
                <td>Abort multipart uploads that have been in progress longer than N days</td>
              </tr>
            </tbody>
          </table>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">API Usage</h3>
<pre class="mb-3"><code class="language-bash"># Set lifecycle rule (delete objects older than 30 days)
curl -X PUT "{{ api_base }}/&lt;bucket&gt;?lifecycle" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '[{
    "ID": "expire-old-objects",
    "Status": "Enabled",
    "Prefix": "",
    "Expiration": {"Days": 30}
  }]'

# Abort incomplete multipart uploads after 7 days
curl -X PUT "{{ api_base }}/&lt;bucket&gt;?lifecycle" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '[{
    "ID": "cleanup-multipart",
    "Status": "Enabled",
    "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 7}
  }]'

# Get current lifecycle configuration
curl "{{ api_base }}/&lt;bucket&gt;?lifecycle" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"</code></pre>

        <div class="alert alert-light border mb-0">
          <div class="d-flex gap-2">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-info-circle text-muted mt-1 flex-shrink-0" viewBox="0 0 16 16">
              <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>
              <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
            </svg>
            <div>
              <strong>Prefix Filtering:</strong> Use the <code>Prefix</code> field to scope rules to specific paths (e.g., <code>"logs/"</code>). Leave empty to apply to all objects in the bucket.
            </div>
          </div>
        </div>
      </div>
    </article>
    <article id="metrics" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">13</span>
          <h2 class="h4 mb-0">Metrics History</h2>
        </div>
        <p class="text-muted">Track CPU, memory, and disk usage over time with optional metrics history. Disabled by default to minimize overhead.</p>

        <h3 class="h6 text-uppercase text-muted mt-4">Enabling Metrics History</h3>
        <p class="small text-muted">Set the environment variable to opt-in:</p>
<pre class="mb-3"><code class="language-bash"># PowerShell
$env:METRICS_HISTORY_ENABLED = "true"
python run.py

# Bash
export METRICS_HISTORY_ENABLED=true
python run.py</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">Configuration Options</h3>
        <div class="table-responsive mb-3">
          <table class="table table-sm table-bordered small">
            <thead class="table-light">
              <tr>
                <th>Variable</th>
                <th>Default</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><code>METRICS_HISTORY_ENABLED</code></td>
                <td><code>false</code></td>
                <td>Enable/disable metrics history recording</td>
              </tr>
              <tr>
                <td><code>METRICS_HISTORY_RETENTION_HOURS</code></td>
                <td><code>24</code></td>
                <td>How long to keep history data (hours)</td>
              </tr>
              <tr>
                <td><code>METRICS_HISTORY_INTERVAL_MINUTES</code></td>
                <td><code>5</code></td>
                <td>Interval between snapshots (minutes)</td>
              </tr>
            </tbody>
          </table>
        </div>

        <h3 class="h6 text-uppercase text-muted mt-4">API Endpoints</h3>
<pre class="mb-3"><code class="language-bash"># Get metrics history (last 24 hours by default)
curl "{{ api_base | replace('/api', '/ui') }}/metrics/history" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Get history for specific time range
curl "{{ api_base | replace('/api', '/ui') }}/metrics/history?hours=6" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Get current settings
curl "{{ api_base | replace('/api', '/ui') }}/metrics/settings" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;"

# Update settings at runtime
curl -X PUT "{{ api_base | replace('/api', '/ui') }}/metrics/settings" \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: &lt;key&gt;" -H "X-Secret-Key: &lt;secret&gt;" \
  -d '{"enabled": true, "retention_hours": 48, "interval_minutes": 10}'</code></pre>

        <h3 class="h6 text-uppercase text-muted mt-4">Storage Location</h3>
        <p class="small text-muted mb-3">History data is stored at:</p>
        <code class="d-block mb-3">data/.myfsio.sys/config/metrics_history.json</code>

        <div class="alert alert-light border mb-0">
          <div class="d-flex gap-2">
            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-info-circle text-muted mt-1 flex-shrink-0" viewBox="0 0 16 16">
              <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z"/>
              <path d="m8.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533L8.93 6.588zM9 4.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0z"/>
            </svg>
            <div>
              <strong>UI Charts:</strong> When enabled, the Metrics dashboard displays line charts showing CPU, memory, and disk usage trends with a time range selector (1h, 6h, 24h, 7d).
            </div>
          </div>
        </div>
      </div>
    </article>
    <article id="troubleshooting" class="card shadow-sm docs-section">
      <div class="card-body">
        <div class="d-flex align-items-center gap-2 mb-3">
          <span class="docs-section-kicker">14</span>
          <h2 class="h4 mb-0">Troubleshooting &amp; tips</h2>
        </div>
        <div class="table-responsive">
          <table class="table table-sm align-middle docs-table mb-0">
            <thead>
              <tr>
                <th scope="col">Symptom</th>
                <th scope="col">Likely cause</th>
                <th scope="col">Fix</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>403 from API despite Public preset</td>
                <td>Policy not saved or ARN mismatch</td>
                <td>Reapply the preset and confirm <code>arn:aws:s3:::bucket/*</code> matches the bucket name.</td>
              </tr>
              <tr>
                <td>UI shows stale policy/object data</td>
                <td>Browser cached prior state</td>
                <td>Refresh; the server hot-reloads <code>data/.myfsio.sys/config/bucket_policies.json</code> and storage metadata.</td>
              </tr>
              <tr>
                <td>Presign dialog returns 403</td>
                <td>User lacks required <code>read/write/delete</code> action or bucket policy denies</td>
                <td>Update IAM inline policies or remove conflicting deny statements.</td>
              </tr>
              <tr>
                <td>Large uploads fail instantly</td>
                <td><code>MAX_UPLOAD_SIZE</code> exceeded</td>
                <td>Raise the env var or split the object.</td>
              </tr>
              <tr>
                <td>Requests hit the wrong host</td>
                <td>Proxy headers missing or <code>API_BASE_URL</code> incorrect</td>
                <td>Ensure your proxy sends <code>X-Forwarded-Host</code>/<code>Proto</code> headers, or explicitly set <code>API_BASE_URL</code> to your public domain.</td>
              </tr>
              <tr>
                <td>Large folder uploads hitting rate limits (429)</td>
                <td><code>RATE_LIMIT_DEFAULT</code> exceeded (200/min)</td>
                <td>Increase rate limit in env config, use Redis backend (<code>RATE_LIMIT_STORAGE_URI=redis://host:port</code>) for distributed setups, or upload in smaller batches.</td>
              </tr>
            </tbody>
          </table>
        </div>
      </div>
    </article>
  </div>
  <div class="col-xl-4">
    <aside class="card shadow-sm docs-sidebar">
      <div class="card-body">
        <h3 class="h6 text-uppercase text-muted mb-3">On this page</h3>
        <ul class="list-unstyled docs-toc mb-4">
          <li><a href="#setup">Set up &amp; run</a></li>
          <li><a href="#background">Running in background</a></li>
          <li><a href="#auth">Authentication &amp; IAM</a></li>
          <li><a href="#console">Console tour</a></li>
          <li><a href="#automation">Automation / CLI</a></li>
          <li><a href="#api">REST endpoints</a></li>
          <li><a href="#examples">API Examples</a></li>
          <li><a href="#replication">Site Replication</a></li>
          <li><a href="#versioning">Object Versioning</a></li>
          <li><a href="#quotas">Bucket Quotas</a></li>
          <li><a href="#encryption">Encryption</a></li>
          <li><a href="#lifecycle">Lifecycle Rules</a></li>
          <li><a href="#metrics">Metrics History</a></li>
          <li><a href="#troubleshooting">Troubleshooting</a></li>
        </ul>
        <div class="docs-sidebar-callouts">
          <div>
            <div class="small text-uppercase text-muted">API base</div>
            <code class="d-block">{{ api_base }}</code>
          </div>
          <div>
            <div class="small text-uppercase text-muted">Sample user</div>
            <code class="d-block">localadmin / localadmin</code>
          </div>
          <div>
            <div class="small text-uppercase text-muted">Logs</div>
            <span class="text-muted small">logs/api.log · logs/ui.log</span>
          </div>
        </div>
        <div class="mt-4">
          <p class="small text-muted mb-1">Need more automation? Extend <code>app/s3_api.py</code> or wrap <code>run_api.py</code> with gunicorn for production-style deployments.</p>
        </div>
      </div>
    </aside>
  </div>
</div>
{% endblock %}