Repository: celestiaorg/celestia-app

Issue:
Refine CELESTIA_HOME usage
### Problem
* `CELESTIA_HOME` conflicts with celestia-node's `CELESTIA_HOME`
* `CELESTIA_HOME` is used as `CELESTIA_HOME/.celestia-app` rather then as override for `~/.celestia-app`

### Proposal
* Rename `CELESTIA_HOME` to `CELESTIA_APP_HOME`
* Ensure `CELESTIA_APP_HOME` overrides `~/.celestia-app`, aligning with `--home` flag (cc @rach-id )

Follow up from https://github.com/celestiaorg/celestia-node/issues/4207#issuecomment-2796276455

- [x] v3.x #4667
- [x] v4.x (main) #4666

Hints from issue comments:
@Susmita-Dey: Hello @Wondertan Please assign it to me. I'll make a PR after that.@rootulp: > 1. Rename CELESTIA_HOME to CELESTIA_APP_HOME

If we do this, we should deprecate it on the v3.x branch . In v4.x we can remove the old env variable. This means you'll need two PRs:

1. A PR targeting v3.x that deprecates the existing env variable and introduces the new one. If the old env variable is used, log a warning.
2. A PR targeting v4.x that only uses the new env variable


@Susmita-Dey: Hey @Wondertan May I know when you're gonna launch v4? Asking this bcoz if v4 would be launched very soon then there won't be any of adding it to v3 as it will get deprecated@Wondertan: No worries, it wont get deprecated even if version number increments. @Susmita-Dey: > No worries, it wont get deprecated even if version number increments.

@Wondertan @rach-id I just need your guidance in which file shall I make the change as I see there are many files containing `CELESTIA_HOME`. Also, need clearance on **Ensure CELESTIA_APP_HOME overrides ~/.celestia-app, aligning with --home flag**@Wondertan: I have no context on such details, so deferring to @rach-id @rach-id: As stated in this comment, https://github.com/celestiaorg/celestia-app/issues/4532#issuecomment-2797295805, you will need two PRs, one to deprecate and make the change. The other to remove and only rely on the new environment variable.

The changes will generally go here: https://github.com/celestiaorg/celestia-app/blob/main/app/init.go

Technically, you will define a new environment variable called: `APP_HOME`, but the issue is with how it will be passed to the https://github.com/celestiaorg/cosmos-sdk/blob/e6823aa2b0a614a6517371f2da6971488837693d/client/v2/helpers/home.go#L17-L48

You either will need to copy that method to Celestia-app so that we have total control over the home directory setup. Or we might want to make the changes in the cosmos-sdk. If we choose the latter, then that would mean an extra 2 PRs to our fork of the comsos-sdk, `v0.46.x-celestia` for v3.x and `v0.50.x-celestia` for main.@adlerjohn: FYI the behavior was changed to make `CELESTIA_HOME` be the actual directory in #4400. So v4 already has the behavior fixed (but not the environment variable name).

Solution patch:
diff --git a/README.md b/README.md
index 887b69db..babccea1 100644
--- a/README.md
+++ b/README.md
@@ -100,9 +100,10 @@ celestia-appd --help
 
 ### Environment variables
 
-| Variable        | Explanation                                                       | Default value                                            | Required |
-|-----------------|-------------------------------------------------------------------|----------------------------------------------------------|----------|
-| `CELESTIA_HOME` | Where the application directory (`.celestia-app`) should be saved | [User home directory](https://pkg.go.dev/os#UserHomeDir) | Optional |
+| Variable            | Explanation                                                                     | Default value                                               | Required |
+|---------------------|---------------------------------------------------------------------------------|-------------------------------------------------------------|----------|
+| `CELESTIA_APP_HOME` | Where the application files should be saved.                                    | [`$HOME/.celestia-appd`](https://pkg.go.dev/os#UserHomeDir) | Optional |
+| `CELESTIA_HOME`     | Where the application directory (`.celestia-app`) should be saved (DEPRECATED). | [User home directory](https://pkg.go.dev/os#UserHomeDir)    | Optional |
 
 ### Create your own single node devnet
 
diff --git a/app/init.go b/app/init.go
index 54c6d7b9..aeec557d 100644
--- a/app/init.go
+++ b/app/init.go
@@ -1,6 +1,7 @@
 package app
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 )
@@ -12,9 +13,14 @@ const Name = "celestia-app"
 // to store configs, data, keyrings, etc.
 const appDirectory = ".celestia-app"
 
-// celestiaHome is an environment variable that sets where appDirectory will be placed.
+// celestiaHome is an environment variable that sets where data will be placed.
 // If celestiaHome isn't specified, the default user home directory will be used.
-const celestiaHome = "CELESTIA_HOME"
+const celestiaHome = "CELESTIA_APP_HOME"
+
+// celestiaHomeOld is an environment variable that sets where appDirectory will be placed.
+// If celestiaHomeOld isn't specified, the default user home directory will be used.
+// Deprecated.
+const celestiaHomeOld = "CELESTIA_HOME"
 
 // DefaultNodeHome is the default home directory for the application daemon.
 // This gets set as a side-effect of the init() function.
@@ -26,17 +32,22 @@ func init() {
 		panic(err)
 	}
 	celestiaHome := os.Getenv(celestiaHome)
-	DefaultNodeHome = getDefaultNodeHome(userHome, celestiaHome)
+	celestiaHomeOld := os.Getenv(celestiaHomeOld)
+	DefaultNodeHome = getDefaultNodeHome(userHome, celestiaHome, celestiaHomeOld)
 }
 
 // getDefaultNodeHome computes the default node home directory based on the
 // provided userHome and celestiaHome. If celestiaHome is provided, it takes
-// precedence and constructs the path by appending the application directory.
+// precedence and constructs the path.
 // Otherwise, it falls back to using the userHome with the application directory
 // appended.
-func getDefaultNodeHome(userHome string, celestiaHome string) string {
+func getDefaultNodeHome(userHome string, celestiaHome string, celestiaHomeOld string) string {
 	if celestiaHome != "" {
-		return filepath.Join(celestiaHome, appDirectory)
+		return celestiaHome
+	}
+	if celestiaHomeOld != "" {
+		fmt.Print("warning CELESTIA_HOME is deprecated and will be removed in the next major release. Use CELESTIA_APP_HOME instead.\n")
+		return filepath.Join(celestiaHomeOld, appDirectory)
 	}
 	return filepath.Join(userHome, appDirectory)
 }



Test patch:
diff --git a/app/init_test.go b/app/init_test.go
index f54759a3..0ac49dd0 100644
--- a/app/init_test.go
+++ b/app/init_test.go
@@ -8,42 +8,75 @@ import (
 
 func Test_getDefaultNodeHome(t *testing.T) {
 	type testCase struct {
-		name         string
-		userHome     string
-		celestiaHome string
-		want         string
+		name            string
+		userHome        string
+		celestiaHome    string
+		celestiaHomeOld string
+		want            string
 	}
 
 	testCases := []testCase{
 		{
-			name:         "want .celestia-app when userHome is empty and celestiaHome is empty",
-			userHome:     "",
-			celestiaHome: "",
-			want:         ".celestia-app",
+			name:            "want .celestia-app when userHome is empty and celestiaHome/Old are empty",
+			userHome:        "",
+			celestiaHome:    "",
+			celestiaHomeOld: "",
+			want:            ".celestia-app",
 		},
 		{
-			name:         "want celestia-home/.celestia-app when userHome is empty and celestiaHome is not empty",
-			userHome:     "",
-			celestiaHome: "celestia-home",
-			want:         "celestia-home/.celestia-app",
+			name:            "want celestia-home/.celestia-app when userHome is empty and celestiaHomeOld is not empty",
+			userHome:        "",
+			celestiaHome:    "",
+			celestiaHomeOld: "celestia-home",
+			want:            "celestia-home/.celestia-app",
 		},
 		{
-			name:         "want user-home/.celestia-app when userHome is not empty and celestiaHome is empty",
-			userHome:     "user-home",
-			celestiaHome: "",
-			want:         "user-home/.celestia-app",
+			name:            "want user-home/.celestia-app when userHome is not empty and celestiaHome/Old are empty",
+			userHome:        "user-home",
+			celestiaHome:    "",
+			celestiaHomeOld: "",
+			want:            "user-home/.celestia-app",
 		},
 		{
-			name:         "want celestiaHome to take precedence if both are not empty",
-			userHome:     "user-home",
-			celestiaHome: "celestia-home",
-			want:         "celestia-home/.celestia-app",
+			name:            "want celestiaHomeOld to take precedence if both it and userHome are not empty",
+			userHome:        "user-home",
+			celestiaHome:    "",
+			celestiaHomeOld: "celestia-home",
+			want:            "celestia-home/.celestia-app",
+		},
+		{
+			name:            "want celestia-home when userHome is empty and celestiaHome is not empty",
+			userHome:        "",
+			celestiaHome:    "celestia-home",
+			celestiaHomeOld: "",
+			want:            "celestia-home",
+		},
+		{
+			name:            "want celestiaHome to take precedence if both it and userHome are not empty",
+			userHome:        "user-home",
+			celestiaHome:    "celestia-home",
+			celestiaHomeOld: "",
+			want:            "celestia-home",
+		},
+		{
+			name:            "want celestiaHome to take precedence if both it and celestiaHomeOld are not empty",
+			userHome:        "",
+			celestiaHome:    "celestia-home",
+			celestiaHomeOld: "celestia-home/.celestia-appd",
+			want:            "celestia-home",
+		},
+		{
+			name:            "want celestiaHome to take precedence if all are not empty",
+			userHome:        "user-home",
+			celestiaHome:    "celestia-home",
+			celestiaHomeOld: "celestia-home/.celestia-appd",
+			want:            "celestia-home",
 		},
 	}
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
-			got := getDefaultNodeHome(tc.userHome, tc.celestiaHome)
+			got := getDefaultNodeHome(tc.userHome, tc.celestiaHome, tc.celestiaHomeOld)
 			assert.Equal(t, tc.want, got)
 		})
 	}