When this workflow is the right fit

Use this path when your code already exists locally and you need a shared remote now. Typical triggers:

• A solo project is becoming a team project.
• A server-side repository is needed for deployment pulls.
• You are replacing ad-hoc zip transfer habits with proper versioned collaboration.

If your local folder is not a repository yet, initialize first and make a baseline commit.

Step 1: Prepare the local repository

Confirm state before creating the remote. A clean starting point prevents accidental omissions.

1
2
3

git status
git log --oneline -n 5
git branch -vv

If there is no repository yet:

1
2
3

git init
git add .
git commit -m "Initial commit"

Step 2: Create a bare repository on the remote host

A shared push target is usually a bare repository. Bare means no checked-out working tree, which prevents accidental edits on the remote endpoint. The official concept is documented in the Git documentation at git-scm.com.

On the target server:

1
2
3

mkdir -p /srv/git/project.git
cd /srv/git/project.git
git init --bare

Set directory ownership so your push user can write objects and refs.

Step 3: Wire the remote in your local repository

1
2

git remote add origin user@your-host:/srv/git/project.git
git remote -v

If origin already exists, inspect it. Do not blindly overwrite unless you intend to replace it.

1

git remote set-url origin user@your-host:/srv/git/project.git

Step 4: Push branches intentionally

For first push, set upstream and send only the branch you want as the initial baseline.

1

git push -u origin main

If the repository uses master or a custom branch name, push that branch explicitly.

Step 5: Verify remote state

On local:

1
2

git branch -vv
git ls-remote --heads origin

On remote:

1
2

cd /srv/git/project.git
git for-each-ref --format="%(refname:short) %(objectname:short)"

The branch hashes should match what you expect from local history.

Common errors and fast recovery

Permission denied (publickey)

Check SSH key presence, authorized_keys, and file permissions in the remote user account.

remote: fatal: unable to create temporary object directory

Ownership on the bare repo path is wrong. Fix owner and group, then retry push.

src refspec main does not match any

No commit exists on that branch yet, or you are using a different branch name.

Push rejected due to non-fast-forward

The remote branch has commits you do not have locally. Fetch and reconcile first:

1
2

git fetch origin
git log --oneline --left-right --graph origin/main...main

Practical caution

Do not store a bare repo under random home directories with mixed permissions. It works until the first maintenance rotation. Use one stable directory, one operational group, and explicit ownership policy.

FAQ

Should I create one bare repo per project?

Yes. Keep one dedicated bare repository per project for clean access boundaries.

Can I push tags now or later?

Either is fine. I usually push tags after branch baseline verification.

Is HTTPS remote better than SSH?

For automation and server-side operations, SSH is usually simpler to maintain.

Related reading

• Git and SVN hub
• Migration patterns
• Deployment playbook

Why most prompt snippets break over time

The common copy-paste prompt one-liner works for a while, then you see weird cursor jumps or broken wrapping after long commands. That usually means non-printing color sequences were not wrapped correctly, so Bash miscounts prompt width.

Bash escape behavior is documented in the GNU Bash manual at gnu.org. Use it as the source of truth whenever prompt behavior looks inconsistent.

Step 1: Add a branch helper

Put this in your shell rc file:

1
2
3

parse_git_branch() {
  git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --short HEAD 2>/dev/null
}

This returns branch name when available and short commit id in detached HEAD state.

Step 2: Wrap color escapes correctly

For Bash, non-printing sequences must be wrapped in \[ and \].

1
2
3

GREEN='\[\e[32m\]'
GRAY='\[\e[90m\]'
RESET='\[\e[0m\]'

Step 3: Build PS1 with conditional branch display

1

export PS1='${GRAY}\u@\h ${RESET}\w${GREEN}$(b=$(parse_git_branch); [ -n "$b" ] && echo " [$b]")${RESET}\$ '

Keep it simple. If you load many subprocess-heavy helpers in PS1, every prompt draw gets slower.

Readability tips

• Avoid bright saturated colors that obscure directory context.
• Keep branch marker compact, for example [main].
• Use one branch color across machines for quick visual consistency.

Performance notes

On large repositories, Git status calls can be expensive. Prefer branch-only detection unless you specifically need dirty-state indicators.

Caution

If your prompt appears to split lines in the wrong place, review escaping first. Most prompt bugs are formatting math bugs, not shell bugs.

FAQ

Does this work in zsh?

The logic is similar, but prompt escape syntax differs. Use zsh-native prompt formatting there.

Can I show dirty state too?

Yes, but test speed in large repositories before keeping it enabled.

Should I use global shell config for all machines?

Use a shared base and machine-specific overrides for paths and host tags.

Related reading

• Git and SVN hub
• Shell snippets
• Migration patterns

Why dual-protocol windows still matter

In ideal systems, you flip to HTTPS-only instantly. In real systems, old clients, webhook providers, or stale integrations often need a short transition window. Serving both protocols buys control, as long as you enforce a clear timeline and monitor actively.

The Node.js HTTPS server API reference is in the official docs at nodejs.org.

Step 1: Load key, certificate, and chain safely

1
2
3
4
5
6
7
8
9
10
11
12

const fs = require('fs');
const https = require('https');
const http = require('http');
const restify = require('restify');

const app = restify.createServer();

const tls = {
  key: fs.readFileSync('/etc/ssl/private/service.key'),
  cert: fs.readFileSync('/etc/ssl/certs/service.crt'),
  ca: fs.readFileSync('/etc/ssl/certs/chain.crt')
};

Use absolute paths and restrictive file permissions.

Step 2: Run HTTPS app and HTTP redirect endpoint

1
2
3
4
5
6
7

https.createServer(tls, app).listen(443);

http.createServer((req, res) => {
  const host = req.headers.host ? req.headers.host.replace(/:\d+$/, '') : 'qugstart.com';
  res.writeHead(301, { Location: `https://${host}${req.url}` });
  res.end();
}).listen(80);

If you are behind a reverse proxy, ensure forwarded protocol headers are handled consistently.

Step 3: Verify locally and externally

• Verify cert chain from command line.
• Verify redirect status and location headers.
• Verify application routes through both paths.
• Verify no mixed-content links in rendered pages.

Redirect caveats that trigger loops

• Proxy terminates TLS but app still thinks request is HTTP.
• Redirect middleware runs on already secure requests.
• Host header includes unexpected port and generates malformed location.

Operational checklist

• Track request counts on HTTP after redirect policy starts.
• Watch for handshake errors and unknown CA events.
• Log redirect target URL during rollout to catch malformed rules early.

FAQ

Should HTTP stay enabled forever?

No. Keep it only for transition, then remove once all critical clients are confirmed.

Can I use one Restify server for both ports?

You can share handlers, but create distinct HTTP and HTTPS listeners for control.

What breaks most often?

Certificate chain order, proxy header assumptions, and broad redirect middleware.

Related reading

• Node.js hub
• SSL and certificates playbook
• Deployment playbook

Migration goals to lock before touching data

Define these in writing first:

• What counts as a successful migration
• Which paths map to trunk, branches, and tags
• How author identities are translated
• How rollback works if validation fails

If this is not explicit, debates happen during cutover and risk spikes.

Step 1: Audit SVN layout and naming anomalies

Inspect repository structure and confirm conventions.

1

svn ls -R <repo-url>

Look for:

• non-standard branch folders
• tags that were edited after creation
• vendor import paths mixed with active code

Step 2: Build author mapping file

Create authors.txt with stable identity mapping:

1
2

jdoe = Jane Doe <jane@example.com>
asmith = Alex Smith <alex@example.com>

If identities are incomplete, gather them before import. Post-import fixes are possible but painful.

Step 3: Run an initial git svn clone

1
2

git svn clone <repo-url> --stdlayout --authors-file=authors.txt project-git
cd project-git

For non-standard layouts, provide explicit trunk, branch, and tag paths.

Step 4: Convert and clean tag representation

SVN tags are directories. In Git they should become immutable refs.

Typical pattern:

• identify imported remote refs
• create local tags from expected tag points
• remove accidental branch-like tag refs

Step 5: Validate branch topology and history

Use targeted comparisons, not visual guesswork.

1
2

git branch -a
git log --graph --decorate --oneline --all | head -n 200

Pick known milestones from SVN and confirm equivalent commits in Git.

Step 6: Dry run cutover with team workflow

Dry run should include:

• clone from candidate Git remote
• build and test from representative branches
• CI trigger checks
• merge flow rehearsal

If one team path fails in dry run, cutover is not ready.

Step 7: Final cutover checklist

• Freeze SVN writes during final sync window.
• Execute final fetch/import and validate counts.
• Push to canonical Git remote.
• Communicate new remote URLs and branch policy.
• Keep SVN read-only for reference period.

Post-cutover hygiene

• Remove obsolete SVN bridge scripts from active workflow.
• Standardize branch naming rules.
• Add protected branch settings in remote platform.
• Document rollback and recovery strategy.

High-risk mistakes to avoid

1. Assuming --stdlayout matches reality without audit.
2. Ignoring rewritten tags that were mutable in SVN.
3. Skipping author map review until after import.
4. Declaring done before team workflow dry run.

FAQ

Should we migrate every historical branch?

No. Migrate branches with operational value, and archive the rest intentionally.

How long should SVN remain available?

Keep read-only access through a defined confidence window and audit period.

Can we rerun import if mapping is wrong?

Yes. Start from a clean Git repository and rerun with corrected mappings.

Related reading

• Git and SVN hub
• Migration patterns
• Checklists

Why these payloads fail in real systems

The request value usually contains two segments separated by a dot:

1. encoded signature
2. encoded payload JSON

Developers often decode one piece correctly and still fail verification because of URL-safe alphabet conversion or padding assumptions.

For Base64 behavior details, MDN has a clear reference section at developer.mozilla.org.

Step 1: Split the payload safely

1
2

encoded_sig, encoded_payload = signed_request.to_s.split('.', 2)
raise 'invalid signed_request format' unless encoded_sig && encoded_payload

Reject malformed values immediately.

Step 2: Convert URL-safe Base64 to standard form

1
2
3
4

def urlsafe_base64_decode(str)
  str += '=' * ((4 - str.length % 4) % 4)
  Base64.decode64(str.tr('-_', '+/'))
end

The - and _ substitutions plus optional padding are the critical details.

Step 3: Verify signature before trusting payload

1
2
3
4

sig = urlsafe_base64_decode(encoded_sig)
payload_raw = urlsafe_base64_decode(encoded_payload)
expected = OpenSSL::HMAC.digest('sha256', app_secret, encoded_payload)
raise 'invalid signature' unless Rack::Utils.secure_compare(sig, expected)

Only parse JSON after signature verification passes.

Step 4: Parse payload and validate claims

Check expected fields and expiration values. Do not trust optional attributes by default.

Caution

Fail closed. If parsing or signature verification fails, reject request and log structured diagnostics without leaking secrets.

FAQ

Why not decode with plain Base64.decode64 directly?

URL-safe variants need alphabet conversion and optional padding normalization first.

Should I still support this flow in new builds?

Use current provider guidance for new integrations. Keep this only where existing traffic requires it.

What should be logged?

Timestamp, request id, failure type, and high-level reason. Avoid logging raw payload secrets.

Related reading

• Ruby and Rails hub
• Checklists
• Migration patterns

What usually goes wrong

Most TLS incidents are not caused by bad keys. They come from chain order mistakes, mixed encoding, or incomplete deployment bundles.

Step 1: Prepare files

You typically need:

• private key file
• server certificate file
• intermediate chain file

Store with strict permissions and predictable paths.

Step 2: Confirm key and cert pairing

1
2

openssl x509 -noout -modulus -in server.crt | openssl md5
openssl rsa  -noout -modulus -in server.key | openssl md5

Hashes should match.

Step 3: Load TLS options in Node.js

1
2
3
4
5
6

const options = {
  key: fs.readFileSync('/etc/ssl/private/server.key'),
  cert: fs.readFileSync('/etc/ssl/certs/server.crt'),
  ca: fs.readFileSync('/etc/ssl/certs/intermediate.crt')
};
https.createServer(options, app).listen(443);

If your provider gives multiple intermediates, keep order explicit.

Step 4: Test handshake and chain exposure

1

openssl s_client -connect your-host:443 -servername your-host -showcerts

Review chain blocks and verification result.

Troubleshooting patterns

• unable to get local issuer certificate means intermediate chain is missing or wrong.
• Browser works but CLI fails can indicate client trust-store differences.
• Intermittent failure after deploy can mean mixed old/new cert files on multi-node rollout.

Caution

Certificate updates should be deployed atomically with restart and verification. Partial rollout with mixed certificate sets can create hard-to-diagnose behavior.

FAQ

Should chain cert be concatenated into cert?

Depends on stack. In Node.js, separate ca is generally clearer for maintenance.

Do I need full service restart?

Yes, unless your process explicitly supports safe live cert reload.

What should I log during rollout?

Handshake errors by client IP and protocol version, plus startup read-path checks.

Related reading

• Node.js hub
• SSL and certificates playbook
• Deployment playbook

Context first

Teams used this pattern when applications expected local filesystem paths and object-storage-native rewrites were not feasible. It can work for limited cases, but it has sharp edges around metadata semantics, latency, and retry behavior.

Step 1: Install FUSE tooling and mount helper

On older CentOS, package combinations vary. Confirm FUSE is available and loaded before touching bucket mount tools.

Step 2: Configure credentials with strict permissions

Use dedicated IAM credentials with the least required access. Protect credential files so only the service account can read them.

Step 3: Create mount point and mount command

1
2

mkdir -p /mnt/s3-data
s3fs your-bucket /mnt/s3-data -o allow_other -o use_cache=/tmp/s3fs-cache

Adjust options according to your mount helper capabilities.

Step 4: Verify behavior under application account

Many setups appear to work as root but fail under app user. Always test with the same account and process model used in production.

1
2

sudo -u appuser touch /mnt/s3-data/write-test.txt
sudo -u appuser ls -la /mnt/s3-data

Known failure modes

• Directory listings are slower than local disk expectations.
• Rename operations can behave differently than local POSIX assumptions.
• Partial network failures surface as filesystem errors in surprising places.

Practical cautions

Treat this as a compatibility layer, not a high-throughput filesystem. For write-heavy workloads, use direct SDK access to S3 or stage to local/EBS and sync.

Modern alternatives

• Keep hot data on EBS/XFS and sync to S3 for retention.
• Use object storage APIs directly in application code.
• Use transfer jobs for batched upload instead of mounted write paths.

FAQ

Is this pattern still recommended?

Only for constrained compatibility scenarios.

What should I monitor?

Mount availability, I/O latency, and application retry/error behavior.

Can I put this in fstab?

You can, but boot-order and network readiness must be tested carefully.

Related reading

• Linux hub
• Data moves playbook
• Deployment playbook

Why this workflow still appears

Many teams inherit systems that depend on deterministic document output and cannot rewrite immediately. Headless conversion remains useful when isolated, monitored, and constrained.

Step 1: Install office packages and fonts

Conversion quality depends heavily on fonts. Missing fonts do not always throw hard errors. They often produce layout drift that only appears during manual review.

Step 2: Run a direct conversion test

1

soffice --headless --convert-to pdf sample.docx --outdir /tmp

Test with representative documents, not a trivial one-page sample.

Step 3: Design service model

Options:

• Execute one-off conversion command per document.
• Run supervised worker process that consumes queued jobs.

For moderate load, queue-based workers are easier to monitor and restart safely.

Step 4: Handle temp paths and lock files

Use dedicated working directories. Clear stale lock files between retries. Do not run all jobs in shared /tmp without namespacing.

Rendering issues to expect

• Font substitution changes line wrapping.
• Embedded images can shift due to decoder differences.
• Complex table layouts vary across office suite versions.

Operational caution

Treat conversion as an isolated service with clear resource limits. Batch jobs can spike memory and trigger cascading failures if they share resources with web workers.

Verification checklist

• Compare output against baseline templates.
• Validate file count and naming for batch jobs.
• Confirm worker restarts do not duplicate conversions.

FAQ

Is LibreOffice better for current systems?

Usually yes, but migration should include output comparison testing before switch.

How do I avoid stuck conversion processes?

Use supervision, timeouts, and explicit job-level retries with idempotent storage paths.

Can this run in containers?

Yes, but include fonts and locale packages explicitly.

Related reading

• Linux hub
• Deployment playbook
• Shell snippets